Wiki maintenance.

Author: Austin1serb

ui/wiki/.wiki-system/audit-state.json

@@ -2,10 +2,10 @@
   "version": 1,
   "pages": {
     "pages/agent-room.md": {
-      "fingerprint": "sha256:30ea34e6456e5f6645baec030993f3604bdea7819806938eb9029c348ebeabba"
+      "fingerprint": "sha256:f6c8fa8a2c70bfa5ae545c8be19bf971c22c8ee9e27ede29435260c20d727882"
     },
     "pages/architecture.md": {
-      "fingerprint": "sha256:c81653074c5bd2d05a27e27f8d0926d4ad65fc2fd1e71e2b4b1a1efbf5e07281"
+      "fingerprint": "sha256:99373a2dce4565b530839b234fd4c60905f6e03e4e4aa6e87174d9f76a8d972d"
     }
   }
 }

ui/wiki/pages/architecture.md

@@ -2,6 +2,7 @@
 summary: "Dashboard data flow, component ownership, API boundary, steering behavior, and tool-call inspection."
 paths:
   - src/App.tsx
+  - vite.config.ts
   - src/hooks/useAgents.ts
   - src/lib/api.ts
   - src/types.ts
@@ -18,6 +19,8 @@ paths:
 
 `useAgents` starts one `GET /ui/api/agents` snapshot and opens `EventSource("/ui/api/events")` concurrently. Snapshot merge keeps any newer agent values already received through SSE. Each `agent_changed` event replaces that agent in place by ID; newly observed agents append. The initial snapshot determines card order so concurrent activity does not make agent cards trade positions while the dashboard is being watched.
 
+SSE reconnect does not fetch another snapshot or replay missed events. An agent unchanged after reconnection may remain stale until a later event or page refresh. Preserve the initial snapshot/SSE merge when changing startup behavior.
+
 Browser types in `src/types.ts` mirror observer snapshots: agent identity/task slug, current call, recent calls, and steering instructions. Keep changes aligned with server observer payloads in root repo `src/server/agent-observer.ts`.
 
 ## Component Ownership

wiki/.wiki-system/audit-state.json

@@ -2,64 +2,67 @@
   "version": 1,
   "pages": {
     "pages/architecture-map.md": {
-      "fingerprint": "sha256:cb1ef20f9bc421eed97fdac17a00cb9c00ecd517f2be6b6ac9e2e12cb587aa99"
+      "fingerprint": "sha256:bff22788604208aeded3cfc47591e6ba07fd64fd59487fd6399e21682da8ca15"
     },
     "pages/computer-use.md": {
       "fingerprint": "sha256:f09a8e4dbd4a8f22f95f64853ee2aa6c435f3893e680324aa52fe027bde90cf3"
     },
     "pages/http-transport.md": {
-      "fingerprint": "sha256:c7f4992b4b68eef10a11b2351b1256521bcdcff995de80f219ab5b4dbac2ba72"
+      "fingerprint": "sha256:eecbddc97c8cd7cacf9b594faac983b77a9ce8ec4d66a8cdd68ff215759c26d6"
     },
     "pages/mcp-tool-surface.md": {
-      "fingerprint": "sha256:47ee99a36d504a7694624cdb76f1d79480c494bac1743276640d065a66c2fe29"
+      "fingerprint": "sha256:bd92807350aa4664261bed4cddfc14000d338203f09bf43b23ebf667b7978a7a"
     },
     "pages/operations/audit-logging.md": {
-      "fingerprint": "sha256:a999d262de22aab08f1e43e26776155960bd7ab2ce66d27ec185189a15527d56"
+      "fingerprint": "sha256:8e44d3c8605e387caae5a3f7453b8bf5b81b6f5cfff96ab4072a3b584ad69fee"
     },
     "pages/operations/build-and-test.md": {
-      "fingerprint": "sha256:761f48151f4bbce77384bf00993de91470f8d0b64179f39f72af13d9daf065d7"
+      "fingerprint": "sha256:da425cfd43d4e1f4a424eabcae278c3b02253040da8241540018f7bb0ccd9fca"
     },
     "pages/operations/configuration-and-startup.md": {
-      "fingerprint": "sha256:5e1ad926f7c46fb8028095b4db721791f384efcfb2b3317754d1d1a3fc0eb847"
+      "fingerprint": "sha256:fd93f326a33d4870db37a7a30d0e2da36a384928d04cee4bf8b0a982d5aae5b6"
     },
     "pages/operations/secret-handling.md": {
-      "fingerprint": "sha256:287d62220386d57ae3c6ae4384fd3064d5bafc64179332ece9592c712ee08307"
+      "fingerprint": "sha256:45dea3a4f73ef57419ecc4aa7f925da8b72069960273a7a3871b790baad68fde"
     },
     "pages/persistent-shell-runtime.md": {
-      "fingerprint": "sha256:735c1fe02235b5c985d753f4e82e067855fae4832c0c6cc32c556aacaf18e73c"
+      "fingerprint": "sha256:40c04c99284c01fe721fc09a24db30732f95ecfa91254c79699463a03e2c5e52"
     },
     "pages/project/open-questions-and-risks.md": {
-      "fingerprint": "sha256:1c7b45e383d332634cbc978883aabcec7c537989c047227402953cb1fe4df62b"
-    },
-    "pages/project/roadmap.md": {
-      "fingerprint": "sha256:b15706871662456a02b6f93bad152aeb063cfb4c6103085fdbd65937bf1324de"
+      "fingerprint": "sha256:027665a0be7f7ee941f8a466092d6ecb8e7316a129d3949699f306b1928a4a95"
     },
     "pages/subagents/browser-chatgpt-subagents.md": {
-      "fingerprint": "sha256:abde3d7c603d7ef72cfd4f49fa258c7d94cd9aa2834032829e1f237da7cd8301"
+      "fingerprint": "sha256:dd1fb67c71c89dc4910c6a5c25b6316aa023b17dd6cedd9fa15abf4230cebc91"
     },
     "pages/subagents/chatgpt-cdp-transport.md": {
-      "fingerprint": "sha256:af4c927963990b323b5f1faa2f928a65f0ddb50159afa0a90d94f0904ff954d9"
+      "fingerprint": "sha256:15ff575d837d7c6ffac5c643789af6965d1694845a1b06c9f7a29c7b6e340510"
     },
     "pages/subagents/subagent-completion.md": {
-      "fingerprint": "sha256:c004a1500ebacc1a0a095e50eabf8567a3d7ad152d16ae4600ebd812963a9ed0"
+      "fingerprint": "sha256:faa46b7d5e26085ba100a0ece3bfee6b00e7ad07ed82cc8903ce68f18422990a"
     },
     "pages/subagents/subagent-tracking.md": {
-      "fingerprint": "sha256:51f58adb652203f74aa169f407edead0a691c8c5bedf6c6c441424daf9f6a3ae"
+      "fingerprint": "sha256:4202ba62a9c6246565fa3d12b590cf603e84a4a832bcd0d055f9b379363d898a"
     },
     "pages/tool-naming-and-schema-design.md": {
-      "fingerprint": "sha256:775af48d644a19a242f68c3871aebeddc6670091c4839487c743815b1c616477"
+      "fingerprint": "sha256:b22abdd4e82d74afba525b8c3b0109fe1d198cb5865c3956daf411562c799b4c"
     },
     "pages/tools/apply-patch.md": {
       "fingerprint": "sha256:4c3406a671f3e6ef42bb9ea185d1efa482044a14a034d81c39452b4b47853d1e"
     },
+    "pages/tools/clones.md": {
+      "fingerprint": "sha256:faa03f46419a702d7b5837a6619a39d6b2a00b95438d24aa3da26cd12296fb9c"
+    },
+    "pages/tools/fetch-url.md": {
+      "fingerprint": "sha256:126ca24e7299c91452d2305e53533ec511ac2d2f80abffce527f4b5dd902d1fd"
+    },
     "pages/tools/shell-run.md": {
       "fingerprint": "sha256:7f506ee5436e66cb8505be8325089b5686b5dc40a67cea0445b851cf22f3880c"
     },
     "pages/tools/subagent.md": {
-      "fingerprint": "sha256:4a8a5f342ea37dfb35ac4826b78166170fb5d9e7ba041b71a6725f9e2d5f834f"
+      "fingerprint": "sha256:f9d67c298319058a4b8f161aa1b0a0e13013b884bf8cae6c89fdeba1b29c6dd7"
     },
     "pages/workspace-tooling.md": {
-      "fingerprint": "sha256:28510faec4534aca399c7b76bbf7c7182db060968298dbc8abbf50f5b671517c"
+      "fingerprint": "sha256:c64d6bc964ad322e8947cf2cb3d5b1203188bc1df55f7ba5a4e1916bd052fd1f"
     }
   }
 }

wiki/AGENTS.md

@@ -21,8 +21,6 @@ summary: "Concise description of this page."
 paths:
   - src/related-files/
   - src/related-file.ts
-read_more:
-  - pages/related-wiki-page.md
 ---
 
 [content]

wiki/index.md

@@ -6,11 +6,11 @@
 - [Architecture Map](./pages/architecture-map.md) — Process-level architecture and request flow across Shellby's HTTP boundary, shared runtime services, and capability handlers.
 - [Computer Use](./pages/computer-use.md) — Focused Computer Use execution through Peekaboo, including snapshots, coordinates, background delivery, and cursor-host ownership.
 - [HTTP Transport](./pages/http-transport.md) — Local HTTP/MCP routing, ngrok trust boundary, remote owner binding, request lifetime, and shared process state.
-- [MCP Tool Surface](./pages/mcp-tool-surface.md) — Published MCP tools and the shared registration, output, instruction, pagination, and capability boundaries shaping their contracts.
+- [MCP Tool Surface](./pages/mcp-tool-surface.md) — MCP registration, startup prompt loading, result projection, and routing to capability contracts.
 - [Operations](./pages/operations/index.md) — Operational setup, validation, logging, and secret-handling knowledge for running and maintaining Shellby MCP.
 - [Persistent Shell Runtime](./pages/persistent-shell-runtime.md) — Persistent shell manager and session internals, including lifecycle, transcripts, concurrency, polling, and recovery.
 - [Project](./pages/project/index.md) — Project-level risks, roadmap ideas, and evaluation research that guide future Shellby MCP work.
 - [Subagents](./pages/subagents/index.md) — Browser-backed ChatGPT subagent architecture, completion, recovery, and private ChatGPT transport behavior.
 - [Tool Naming and Schema Design](./pages/tool-naming-and-schema-design.md) — Model-facing conventions for tool names, routing descriptions, schemas, parameter descriptions, and compact outputs.
-- [Tools](./pages/tools/index.md) — Caller-facing contracts for Shellby MCP's core shell, patch, and subagent tools.
+- [Tools](./pages/tools/index.md) — Caller-facing contracts for shell execution, patching, browser delegation, clones, and resource fetching.
 - [Workspace Tooling](./pages/workspace-tooling.md) — Default coding workspace behavior and the dynamic reusable-skill catalog exposed through skill_list and skill_load.

wiki/maintenance.md

@@ -5,33 +5,44 @@ Wiki pages and raw-source metadata are agent-authored. Generated indexes are der
 ## Front Matter Metadata
 
 - `summary` is required for routable pages and should stay concise. `wiki clean` warns above 240 characters.
-- `paths` is optional and names repository files or directories the page helps explain.
-- `read_more` is optional lateral routing for a specific next page that is not obvious from the generated index hierarchy; use it sparingly and omit it from most pages.
+- `paths` is optional and defines the source scope whose meaningful changes could invalidate the page's knowledge. Do not aim for complete repository path coverage. `project-overview.md` should usually omit `paths` unless a narrow source scope genuinely governs its global knowledge.
 - Update front matter when a page's knowledge scope changes.
 
 When creating a nested knowledge directory, add an `index.md` with only a `summary` in front matter. `wiki clean` generates and maintains the index body.
 
 ## Page Structure
 
 These are not hard rules but heuristics:
-
 - Keep one cohesive subject per page.
+- `wiki clean` warns when `project-overview.md` exceeds 2,000 words or another routable page exceeds 3,000 words. These are review thresholds, not targets or limits.
 - Keep indexes small enough to route cheaply. Roughly 10–20 entries is a useful heuristic, not a limit.
 - Split large knowledge areas into meaningful nested directories. The hierarchy may recurse as needed.
 - Keep supporting evidence under `raw/`.
 
+## Freshness Audit
+
+`wiki audit` compares the current Git-visible contents under each page's `paths` with the fingerprint recorded when that page was last reviewed. A mismatch means review is suggested, not that the page is necessarily stale. Pages without `paths` are not audited.
+
+- Keep `.wiki-system/audit-state.json` committed with the wiki, but treat `.wiki-system/` as machine-maintained state; do not read or edit it directly.
+- After creating or migrating a reviewed wiki, run `wiki audit baseline` once. It records only pages without an existing baseline and never clears later review warnings.
+- After reviewing a reported page against current source, update the page if needed, then run `wiki audit mark <wiki-page>` to record the reviewed state. Mark it even when review confirms that no wiki content change is needed.
+- `wiki audit` includes tracked files and non-ignored untracked working-tree files, so it can detect relevant changes before they are committed.
+- Repeated irrelevant audit warnings suggest a page's `paths` are too broad; missed stale knowledge suggests they are too narrow.
+
 ## Raw Sources
 
-Raw sources are evidence captured into the wiki, often copied from original human-authored documents or created from confirmed interviews.
+Raw sources are read-only captured evidence originating outside the maintained semantic wiki, such as confirmed interview transcripts or copied human-authored documentation.
 
-- When first ingesting a Markdown source, add front matter containing only a concise `summary` describing what the source is and why it matters. Write summaries as routing signals. A summary should help an agent decide whether to open the page from an index, including the behaviors or boundaries that distinguish it from neighboring pages.
-- Preserve the source body as captured. After a raw source is created, do not edit that file without explicit user approval.
+- Ingest external evidence by copying it into `raw/`; never move or delete the original source. Capture all raw evidence as Markdown, converting copied source material to Markdown when necessary.
+- When first ingesting a raw source, add front matter containing only a concise `summary` describing what the source is and why it matters. Write summaries as routing signals. A summary should help an agent decide whether to open the page from an index, including the behaviors or boundaries that distinguish it from neighboring pages.
+- Preserve the captured body after ingestion. Do not edit an existing raw source without explicit user approval.
 - `wiki clean` generates `raw/index.md` from raw Markdown summaries, including Markdown stored in nested raw directories.
-- Non-Markdown evidence may live under `raw/` unchanged; it is not included in the generated raw index.
 
-## Context Log
+## Decision Log
+
+`log.md` is this wiki’s existing decision log; it preserves major historical reasoning that explains why the project took its current direction. Add a concise entry when a significant decision, reversal, discovery, rejected approach, validation, or lesson from real usage would help a future agent and the reasoning is not obvious from the current code, wiki, or Git history. Do not use it as a changelog. Keep existing chronological entries intact; `test/wiki-log.test.ts` validates their order. No rename to `decision-log.md` is needed for maintenance.
 
-`log.md` is an append-only record for durable historical context that cannot be cheaply reconstructed from Git, the current wiki, or raw evidence. Use it for things like important architecture decisions or reversals and meaningful approaches that were tried and abandoned. Most changes should not add a log entry.
+Before finishing substantial wiki maintenance, ask whether the work exposed or changed durable reasoning that will still matter after the implementation details are forgotten. If yes, append one concise entry.
 
 ## Cleanup