docs(user-docs): reconcile user docs for the v0.8.5 pre-release

[vybe]

Summary

User-facing documentation reconciliation for the v0.8.5 pre-release. Reconciles docs/user-docs/ against everything merged since v0.8.0 (~130 commits) and adds the v0.8.5 What's New page. Docs-only — no code changes.

New pages

• whats-new/v0.8.5.md — user-facing release highlights
• collaboration/rooms.md — shared multi-agent sessions (enterprise, behavior-only)
• automation/agent-reminders.md — one-shot deferred self-triggers
• operations/telemetry.md — local capture + opt-in fleet sharing
• sharing-and-access/customer-portal.md — enterprise client chat app

Key corrections (were materially wrong/stale)

• voice-replies rewritten to the v2 per-message model
• monitoring retention: removed a false "5,000 rows/cycle" claim; added the blast-radius guard + admin approval + community floor and all 7 windows
• dashboard / agent-network: removed the decommissioned Graph view
• SSH access: corrected to key-only (password auth was removed)

Additive updates

Slack (per-channel consent, completion report-back, configurable rate limits, per-agent dedicated bots), per-user GitHub tokens, PAT-free public clone, skill packages + runner, loop failure policy, task-completion report-back, resilient system deploy + default-system seed, display labels, Fable 5 / Sonnet 5, unattended / agent-driven install.

FAQ

New grounded Q&As and stale-answer fixes across every topic; faq/README.md regenerated from live headings (288 questions, up from 264).

README

Fixed the Cornelius template links in the root and onboarding READMEs to point at github.com/Abilityai/cornelius (was the empty agent-cornelius repo).

Verification

• 1125 relative links checked — 0 broken
• Enterprise-docs CI grep-guard clean; no issue-number/codename leaks
• Deploy-guide public-safety greps clean

Notes / follow-ups

• Enterprise-gated features are documented behavior-only with an enterprise note — no enterprise_* schema or entitlement internals — per the standing open-core docs rule.
• Open follow-up (code, not in this PR): src/backend/config.py DEFAULT_GITHUB_TEMPLATE_REPOS still lists abilityai/agent-cornelius (the in-product default template list) — worth updating to abilityai/cornelius separately.
• What's New ships text-only; a screenshot capture list was handed off for later embedding.

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[AndriiPasternak31]

PR Validation Report — /validate-pr

PR: #1765 — docs(user-docs): reconcile user docs for the v0.8.5 pre-release
Author: @vybe · Branch: docs/v0.8.5-pre-release-user-docs → dev · Files: 48 (+997/−145), docs-only (nothing outside docs/ and README.md)
CI: ✅ green — all 21 checks including guard (enterprise-docs-guard), gitleaks, schema-parity, CodeQL, 6 pytest seed matrices.

Verdict: REQUEST CHANGES — two blocking items, both small. The substance here is unusually strong (22/22 factual spot-checks passed, see below); this is two edits from mergeable.

Summary

Category	Status	Notes
Commit Messages	✅	2 commits, conventional docs(user-docs):, detailed bodies
Base Branch	✅	Targets dev
PR Size	⚠️	48 files — under the 50 threshold; cohesive, no split recommended
Status Auto-Promotion	❌	No issue reference of any kind — see Critical 1
Roadmap	❌	No linked issue in either tracker
Requirements	➖	Docs-only; no new platform capability introduced here
Architecture	➖	architecture.md untouched; no claim in the diff contradicts it
Feature Flows	➖	User-docs are a separate surface from docs/memory/feature-flows/
Security Check	✅	All Step-4 checks clean (detail below)
Infrastructure	➖	No compose / Dockerfile / nginx
Build & Config Packaging	➖	No new src/backend/*.py, no new os.getenv()
Test Adequacy	➖	Docs-only → /review + /cso skip per pipeline table
Code Quality	❌	One real content defect — see Critical 2
Requirements Trace	⚠️	Content traces cleanly to shipped code; process trace to an issue is missing

Factual spot-checks — 22 claims verified against real code, zero contradictions

Checked against origin/dev source, not against architecture.md:

Claim	Verdict	Evidence
Graph view decommissioned; saved graph pref falls back	✅	stores/network.js:55 VIEW_MODES = ['grid','timeline']; removal in 9f766d11 (#1689/#1701)
MCP "~107 tools across 27 modules" (was 93)	✅ exact	27 modules, 107 name: registrations counted
skills.ts 9 · rooms.ts 5 · reminders.ts 3	✅ exact	per-module counts confirmed
Retention has 7 windows	✅	settings_service.py:68 RETENTION_OPS_KEYS = 7; the 8th table row is audit_log, correctly marked exempt
Removal of "capped at 5,000 rows per cycle" → "bounds each transaction, not each sweep"	✅ genuine correction	Old claim was false; most prune accessors drain the whole candidate set
Blast-radius guard = 1,000 rows, fixed constant not a setting	✅	retention_guard.py:87, comment "DELIBERATELY A FIXED CONSTANT, NOT A SETTING"
POST /api/settings/retention/acknowledge admin + human-only, window-bound, single-use	✅	routers/settings.py:272, docstring "THIS ENDPOINT IS THE GATE"
Community floor 5 days, fresh installs only, agent soft-delete exempt	✅	config.py:351; COMMUNITY_FRESH_INSTALL_SEED seeds 4 keys, soft-delete correctly absent
Reminders: min 60 s, max 30 d, 25 pending, 100/day, 4000 chars	✅ all exact	models.py:2092–2103 (2592000 = 30 d)
Loop on_failure default abort; max_consecutive_failures 3	✅	models.py:2005–2006, 2058–2059
Display label GET/PUT /api/agents/{name}/label	✅	routers/agents.py:870, :890
SSH key-only, password path removed	✅	agent_ssh.py:69–70 rejects non-"key"; base-image/Dockerfile:92 PasswordAuthentication no
Fable 5 / Sonnet 5 in picker; Sonnet 5 = 1M	✅	ModelSelector.vue:96–97
--unattended / TRINITY_UNATTENDED	✅	start.sh:17–18
TRINITY_DEFAULT_SYSTEM_MANIFEST skip/override	✅	system_seed_service.py:82
Proactive rate-limit + Slack per-channel endpoints	✅	settings.py:1812/1837; slack.py:654
Telemetry two-gate + 4 env vars + DO_NOT_TRACK	✅	settings.py:213/229; config.py:50–62
FAQ "288 questions across 14 topics" + every per-topic count	✅ all 14 exact	counted ^## headings; total exactly 288
Author's own caveat: config.py still lists agent-cornelius	✅	config.py:331 — self-report is accurate

Note two places where this PR is more accurate than docs/memory/architecture.md (Graph view, the 5,000-row cap) — architecture.md is the stale one, not this PR.

Deletions audit (−145): enumerated every removed line. All justified corrections — stale Graph-view docs, the false 5,000-row cap, pre-v2 always-on voice replies, password SSH, superseded plugin counts, the flat-200K context claim. One exception, Critical 2.

Link integrity: all 946 relative links in the changed files checked — 0 broken.

Security ✅

All Step-4 checks clean. Zero real emails, zero IPs, no .env, no credential files; the one "hardcoded secret" grep hit is a context line referencing the $GITHUB_PAT env var, not a literal.

Placeholder discipline is exemplary. Every URL added across 997 lines: http://localhost (8×), https://github.com (2×), https://your-domain.com (1×). Nothing else. operations/telemetry.md documents TELEMETRY_SHARING_URL by variable name only and never prints the code's default intake hostname (config.py:57) — exactly right for a public repo.

---

Issues found

❌ Critical 1 — No issue reference of any kind

Neither title nor body contains Fixes/Closes/Resolves, nor even a bare #N. Per the skill's Quick Triage this is an automatic ❌. Consequence: issue-status-on-merge.yml has nothing to promote and the work leaves no tracker trace.

Plausible candidates exist in the private tracker (trinity-enterprise#67 "MCP marketplace manual submissions — v0.8.5", #239 "Audit bundled default-system manifest for v0.8.5", #7 "User Docs") but none is referenced.

Fix: one line in the body — Fixes abilityai/trinity-enterprise#N. Cross-tracker form is expected and accepted; just remember the private issue then needs a manual status-in-dev bump (same-repo automation only).

❌ Critical 2 — Orphaned, self-contradicting FAQ paragraph in docs/user-docs/faq/agents.md

I verified this directly in the diff. The heading was replaced but its answer paragraph was left behind:

-## Why can't I create a new agent with the same name as one I just deleted?
+## Can I create a short-lived, disposable agent that cleans itself up?
+
+Yes… it is discarded immediately and completely: the container and its data
+are removed with no soft-delete window and no reserved name. …

 Because deletion is a soft delete, the old agent's record still exists and
 reserves the name until the retention sweep purges it (default: 180 days). …

The stranded paragraph is an unchanged context line, so it now renders directly under the ghost-agent answer and flatly contradicts it — "no reserved name" immediately followed by "reserves the name … 180 days".

Two defects in one edit: users get a self-contradicting answer, and a still-valid FAQ question was silently dropped while its answer survives, mis-attached. The FAQ index generator can't catch this — it builds from headings, so the count stays a consistent 23 and the breakage is invisible to tooling.

Fix: either restore the deleted heading above the stranded paragraph (→ 24 for that topic / 289 total, regenerate the index), or delete the paragraph.

⚠️ Warning 3 — Open-core policy tension; needs an explicit call, not a silent merge

CLAUDE.md's standing rule (trinity-enterprise#45) states public docs carry "the generic open-core seam only … no catalog of specific paid features, no enterprise_* table DDL, and no per-module implementation detail."

This PR publishes exactly such a catalog. whats-new/v0.8.5.md adds a ## Enterprise / "Available on the enterprise tier:" section naming six gated modules (shared rooms, per-agent Slack bots, skill runner, fleet usage-sharing, ghost agents, customer portal); faq/getting-started.md names three inline; collaboration/rooms.md and sharing-and-access/customer-portal.md are dedicated per-module pages with MCP tool signatures, REST endpoint tables, and default budgets (max_messages 60, ttl_hours 24).

The passing guard check does not clear this, and I confirmed why. The guard is a grep for private identifiers, not a semantic catalog check. Its pattern is:

\bSIEM\b|\bSCIM\b|\bclient_portal\b|\bpermissions_matrix\b|\btwo_factor\b|2fa_recovery_codes|\benterprise_(?!features\b|…)[a-z_]+

customer-portal.md:46 names the private route namespace /api/enterprise/client-portal/* — hyphenated. I tested it against the live pattern: no match. \bclient_portal\b is underscore-anchored, and enterprise_[a-z_]+ needs an underscore where the path has a slash. So it evades both rules. There is a genuine gap between what the written rule says and what CI enforces.

This is your call, not CI's — and there's an obvious legitimate tension (you can't sell a tier you may not describe). But it should be resolved explicitly: either amend the CLAUDE.md rule to permit behavior-only paid-feature documentation and tighten the guard to the hyphen form, or trim these pages. Merging as-is leaves the docs and the written rule in contradiction on a public repo.

Suggestions (optional)

• docs/user-docs/images/dashboard-graph-view.png is now referenced 0 times — dead asset from the Graph-view removal.
• README.md case inconsistency within one hunk: table links github.com/**A**bilityai/cornelius, code block says github:**a**bilityai/cornelius. Harmless (org names are case-insensitive).
• File the verified config.py:331 DEFAULT_GITHUB_TEMPLATE_REPOS → abilityai/agent-cornelius follow-up as an issue so it isn't lost when this merges.
• Branch is 1 commit behind origin/dev (trivial).

---

Required before merge

• Add an issue reference with a closing keyword to the body (e.g. Fixes abilityai/trinity-enterprise#N). Cross-tracker is fine — it then needs a manual status-in-dev bump.
• Fix the orphaned paragraph in docs/user-docs/faq/agents.md — restore the deleted heading (and regenerate the FAQ index to 24 / 289) or delete the stranded paragraph.
• Make the open-core call explicit: either amend the CLAUDE.md rule and tighten the guard to catch client-portal, or trim the paid-feature catalog from v0.8.5.md / rooms.md / customer-portal.md.

Happy to push the FAQ fix myself if you'd rather not round-trip — say the word and I'll commit it to this branch.

_{🤖 Validated with Claude Code via /validate-pr}

[AndriiPasternak31]

/validate-pr — APPROVE. Docs-only (48 files, +997/-145).

I spot-checked the four claims labelled "materially wrong/stale" against the code, since a stale-docs PR that ships a new wrong claim is the failure mode worth catching. All four corrections are right:

Correction	Verification
Removed false "5,000 rows/cycle" retention claim	monitoring.md had 1 occurrence on dev, 0 here. Matches architecture.md: six of seven prune accessors loop while True and drain the entire candidate set — RETENTION_CHUNK_SIZE_PER_CYCLE bounds each transaction, not each call. The real bound is the #1644 blast-radius guard, which this PR adds ✅
Removed decommissioned Graph view	dashboard.md 2 → 0. The one remaining mention in agent-network.md is a correct retirement note ("the old live node/edge graph view was retired; the underlying collaboration data still flows and feeds the Timeline") — exactly #1689's semantics ✅
SSH corrected to key-only	Now states key-based only, server never handles a private key, daemon rejects password auth, TTL enforced on the container not just metadata. Matches #1615 (password auth → 400) and #1616 (expired-key sweep on the container authorized_keys, not just Redis metadata) ✅
voice-replies rewritten to the v2 per-message model	Consistent with ent#117: voice is a per-message agent choice via send_voice_reply, not the always-on adapter path ✅

Security scan clean. One grep hit on the hardcoded-secret pattern is a false positive — prose describing GH_TOKEN="$GITHUB_PAT", a variable reference, not a literal.

No file overlap with the #1777 main→dev reconcile (disjoint sets), and it test-merged clean on top of it. CI all green including the full 6-way pytest matrix and regression diff.

Non-blocking:

• 48 files is just under the 50-file split threshold — acceptable here, since it is one coherent docs reconcile against ~130 commits rather than mixed concerns.
• No closing keyword; closes no tracker issue, so nothing strands.