Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

docs: index the 17 living guides omitted from docs/README.md (#11854)

Adam Eivy31bdc1d27c61
diff --git a/docs/README.md b/docs/README.md
index af9958f446..6e83fecf45 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,15 +21,22 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo
| [FEDERATED_MEDIA_PROVIDERS.md](./FEDERATED_MEDIA_PROVIDERS.md) | Authenticated, capacity-aware peer audio provider wire contract and setup |
| [STORAGE.md](./STORAGE.md) | Storage classification contract — PostgreSQL vs filesystem, new-data-store checklist |
| [BACKUP.md](./BACKUP.md) | Filesystem snapshots + PostgreSQL dumps, restore semantics |
+| [BACKUP_PUBLICATION_ADMISSION.md](./BACKUP_PUBLICATION_ADMISSION.md) | Shared admission lease between the server and `portos-cos`, and how snapshot and restore cuts drain in-flight asset publications |
| [PORTS.md](./PORTS.md) | Port allocation (5553–5561) and how 5555/5553/5554 relate |
| [ITERM.md](./ITERM.md) | The Shell page's iTerm2 view — requirements, status states and their fixes, why iTerm2 sessions stay separate from PortOS shells, the clean-room protocol rule |
| [INSTANCE_FEATURES.md](./INSTANCE_FEATURES.md) | Optional per-install features — registry, client-side nav gating, feature groups, reconcile-at-toggle |
| [PM2.md](./PM2.md) | Recommended PM2 ecosystem patterns for sub-projects |
| [DEEP-AUDITS.md](./DEEP-AUDITS.md) | Persistent audit coverage, independent passes, checkpoint/resume and completion rules |
+| [DEEP-AUDITS-LEGACY.md](./DEEP-AUDITS-LEGACY.md) | Legacy (historical) exhaustive Deep audit records and their stored evidence format; new launches no longer run this workflow |
| [QUOTA-BURN.md](./QUOTA-BURN.md) | Quota-burn automation — spending subscription-backed CLI quota before expiry |
| [AI_PROVIDERS.md](./AI_PROVIDERS.md) | The AI Providers page: a run composed from Harness × Method × Service × Model × Effort, its Presets / Harnesses / Services views, compatibility matrix, derived vs legacy presets, and what federates (nothing) |
| [PROVIDER_COMPOSITION.md](./PROVIDER_COMPOSITION.md) | Composite provider ids (`harness.method@service[+bootstrap]`): the grammar, per-harness enablement, bootstrap apps, how every run path resolves one, and the preset-only surfaces |
| [MODEL_ACCESS.md](./MODEL_ACCESS.md) | Scoping a provider to the models your plan entitles you to — free tiers, allow/deny globs, gateway inheritance |
+| [MODEL_TIERS.md](./MODEL_TIERS.md) | Light / Medium / Heavy / Ultra tiers as per-preset routing configuration, and how a task or stage names a tier |
+| [JEV_SETUP.md](./JEV_SETUP.md) | Optional local jev entailment scorer: installing, the pinned model and runtime, and recovery |
+| [PROMPT_GUARD_SETUP.md](./PROMPT_GUARD_SETUP.md) | Abuse Guard (Prompt Guard) runtime: status and install commands, repair behavior, and diagnosing a failed install |
+| [PERSISTENT_MIND_MAINTAINER.md](./PERSISTENT_MIND_MAINTAINER.md) | Opt-in, machine-local development maintainer role for the persistent mind: setup, grants, and activation |
+| [IMAGE_GALLERY.md](./IMAGE_GALLERY.md) | Image gallery reads: legacy full-array response, paged and filtered envelope, and `media_assets` search semantics |
| [MODEL-COMPARISON.md](./MODEL-COMPARISON.md) | Sourced provider/model/effort comparisons, cost estimates and CoS research refresh |
| [THREEJS_MODELS.md](./THREEJS_MODELS.md) | Three.js procedural 3D model generation and trust boundary |
| [features/music-video-autonomous.md](./features/music-video-autonomous.md) | One-prompt autonomous music videos: brief → lyrics → mood board → Suno song → production, optional checkpoints, and the `music-video-autopilot` scheduled task that turns Brain ideas into videos |
@@ -59,16 +66,18 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo
Start with the [product surface map](./features/product-surfaces.md) for a complete, user-facing inventory of the application. The focused guides below explain the features with their own operating contracts.
-App management: [app-wizard](./features/app-wizard.md) · [autofixer](./features/autofixer.md) · [browser](./features/browser.md) · [error-handling](./features/error-handling.md) · [jira-sprint-manager](./features/jira-sprint-manager.md)
+App management: [app-wizard](./features/app-wizard.md) · [app-quality](./features/app-quality.md) · [autofixer](./features/autofixer.md) · [browser](./features/browser.md) · [error-handling](./features/error-handling.md) · [jira-sprint-manager](./features/jira-sprint-manager.md)
-Chief of Staff: [chief-of-staff](./features/chief-of-staff.md) · [cos-agent-runner](./features/cos-agent-runner.md) · [cos-enhancement](./features/cos-enhancement.md) · [self-improvement-audits](./features/self-improvement-audits.md) · [agent-context](./features/agent-context.md) · [agent-skills](./features/agent-skills.md) · [memory-system](./features/memory-system.md) · [claude-ollama](./features/claude-ollama.md) · [grok-box-local-mind](./features/grok-box-local-mind.md) · [fleet-llm-host](./features/fleet-llm-host.md) · [mtplx](./features/mtplx.md) · [slotstream](./features/slotstream.md) · [dflash2](./features/dflash2.md) ([DSpark vs DFlash 2](./research/2026-08-19-dspark-vs-dflash2.md), [Ternary Bonsai 2 27B](./research/2026-09-18-ternary-bonsai-2-27b.md)) · [qwen38-rtx3090](./features/qwen38-rtx3090.md) ([3090 bring-up](./research/2026-08-21-qwen38-rtx3090-vllm.md)) · [sglang-qwen38](./features/sglang-qwen38.md) ([SGLang Hopper/Blackwell evaluation](./research/2026-08-21-sglang-qwen38-27b.md)) · [prompt-manager](./features/prompt-manager.md)
+Chief of Staff: [chief-of-staff](./features/chief-of-staff.md) · [cos-agent-runner](./features/cos-agent-runner.md) · [cos-enhancement](./features/cos-enhancement.md) · [self-improvement-audits](./features/self-improvement-audits.md) · [agent-context](./features/agent-context.md) · [agent-skills](./features/agent-skills.md) · [memory-system](./features/memory-system.md) · [claude-ollama](./features/claude-ollama.md) · [grok-box-local-mind](./features/grok-box-local-mind.md) · [fleet-llm-host](./features/fleet-llm-host.md) · [mtplx](./features/mtplx.md) · [slotstream](./features/slotstream.md) · [dflash2](./features/dflash2.md) ([DSpark vs DFlash 2](./research/2026-08-19-dspark-vs-dflash2.md), [Ternary Bonsai 2 27B](./research/2026-09-18-ternary-bonsai-2-27b.md)) · [qwen38-rtx3090](./features/qwen38-rtx3090.md) ([3090 bring-up](./research/2026-08-21-qwen38-rtx3090-vllm.md)) · [sglang-qwen38](./features/sglang-qwen38.md) ([SGLang Hopper/Blackwell evaluation](./research/2026-08-21-sglang-qwen38-27b.md)) · [prompt-manager](./features/prompt-manager.md) · [development-watchdog](./features/development-watchdog.md) · [review-queue](./features/review-queue.md) · [scheduled-audit-organization](./features/scheduled-audit-organization.md)
+
+Federation: [peer-administration](./features/peer-administration.md) · [tailcat-peers](./features/tailcat-peers.md) · Models: [decision-classifiers](./features/decision-classifiers.md)
- [Persistent Mind continuous play + local context](./features/persistent-mind-continuous-play.md) — explore/invent playbook and mind-adjustable `numCtx` clamps
Identity & self: [digital-twin](./features/digital-twin.md) · [identity-system](./features/identity-system.md) · [soul-system](./features/soul-system.md) · [privacy-center](./features/privacy-center.md) · [post](./features/post.md) (insights design spike: [plans/2026-06-03](./plans/2026-06-03-cross-domain-insights-engine.md))
Knowledge: [brain-system](./features/brain-system.md) · [untrusted messages and GitHub automation](./features/messages-security.md) · [scope adherence](./features/scope-adherence.md)
-Create: [writers-room](./features/writers-room.md) · [fableloom](./features/fableloom.md) · [Eidoverse Worlds integration](./features/eidoverse.md) · [Eidoverse music-video renderer](./EIDOVERSE_VIDEO.md) · [OpenWorld historical reference](./features/openworld.md) · [sprite-export-contract](./features/sprite-export-contract.md) · [video-text-encoders](./features/video-text-encoders.md) · [video-speed-profiles](./features/video-speed-profiles.md) · [video-render-batches](./features/video-render-batches.md) · [video-upscale](./features/video-upscale.md)
+Create: [writers-room](./features/writers-room.md) · [creative-director-video](./features/creative-director-video.md) · [apple-video-options](./features/apple-video-options.md) · [qwen-image-21](./features/qwen-image-21.md) · [fableloom](./features/fableloom.md) · [Eidoverse Worlds integration](./features/eidoverse.md) · [Eidoverse music-video renderer](./EIDOVERSE_VIDEO.md) · [OpenWorld historical reference](./features/openworld.md) · [sprite-export-contract](./features/sprite-export-contract.md) · [video-text-encoders](./features/video-text-encoders.md) · [video-speed-profiles](./features/video-speed-profiles.md) · [video-render-batches](./features/video-render-batches.md) · [video-upscale](./features/video-upscale.md)
Comms & voice: [beeper](./features/beeper.md) · [messages-browser-send](./features/messages-browser-send.md) · [openclaw-operator-chat](./features/openclaw-operator-chat.md) ([pre-build audit](./research/2026-03-31-openclaw-operator-chat-audit.md)) · [stacker-news](./features/stacker-news.md) · [voice](./features/voice.md) ([Jev feasibility](./research/2026-09-30-jev-voice-feasibility.md))
diff --git a/docs/docs-index.test.js b/docs/docs-index.test.js
new file mode 100644
index 0000000000..a31d90ae9d
--- /dev/null
+++ b/docs/docs-index.test.js
@@ -0,0 +1,44 @@
+/**
+ * Index guard for docs/README.md.
+ *
+ * The index opens with "Index of everything under `docs/`", and AGENTS.md sends
+ * contributors there as the documentation entry point. Nothing enforced that
+ * claim, so living guides (JEV_SETUP, PROMPT_GUARD_SETUP, tailcat-peers, ...)
+ * accumulated outside it and were effectively undiscoverable.
+ *
+ * Every top-level docs/*.md and docs/features/*.md must be linked from the
+ * index by its relative path. Decision records, plans, research, and the
+ * point-in-time directories are deliberately out of scope: the index presents
+ * them as examples and per-directory READMEs rather than a complete list.
+ */
+import { readdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { describe, expect, it } from 'vitest';
+
+const DOCS_DIR = dirname(fileURLToPath(import.meta.url));
+const INDEX = readFileSync(join(DOCS_DIR, 'README.md'), 'utf8');
+
+const markdownIn = (dir) =>
+ readdirSync(dir, { withFileTypes: true })
+ .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+ .map((entry) => entry.name);
+
+const LIVING_DOCS = [
+ ...markdownIn(DOCS_DIR).filter((name) => name !== 'README.md'),
+ ...markdownIn(join(DOCS_DIR, 'features')).map((name) => `features/${name}`),
+];
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+describe('docs/README.md index coverage', () => {
+ it('discovers the living docs it guards', () => {
+ expect(LIVING_DOCS).toContain('JEV_SETUP.md');
+ expect(LIVING_DOCS).toContain('features/tailcat-peers.md');
+ });
+
+ it.each(LIVING_DOCS)('links %s by its relative path', (doc) => {
+ const link = new RegExp(`\\]\\((\\./)?${escapeRegExp(doc)}(#[^)]*)?\\)`);
+ expect(INDEX, `docs/README.md must link ./${doc}`).toMatch(link);
+ });
+});
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 7ba56d2abf..8c74a58fe7 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -276,6 +276,7 @@ export const ALWAYS_RUN_TESTS = [
// otherwise merge green.
'docs/api-doc.test.js',
'docs/auth-public-paths-doc.test.js',
+ 'docs/docs-index.test.js',
'docs/deps-doc.test.js',
'docs/features/product-surfaces.test.js',
'scripts/agent-instructions-files.test.js',