> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session17-docs-metadata-and-gitignore-closeout/spec.md). # Session Specification **Session ID**: `phase40-session17-docs-metadata-and-gitignore-closeout` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: ccfa7231ab3def76e302b062f1528abdd00bbba3 *** ## 1. Session Overview This session updates AI OS documentation and repository metadata rationale after the Phase 40 implementation sessions that changed Hermes behavior. The work aligns public docs, local API notes, agent-page docs, data-contract docs, voice docs, changelog notes, and handoff notes with the behavior that shipped in Sessions 01 through 16. The session is next because the deterministic project analysis reports Phase 40 as in progress, no current session is active, Sessions 01 through 16 are complete, and Session 17 is the earliest unfinished current-phase session. Session 18 depends on Session 17 documentation and metadata closeout, so this plan keeps the work bounded to documentation, metadata decisions, and validation scans. The implementation must describe current AI OS behavior only. It must not add claims for unimplemented upstream behavior, must not rename Hermes Intelligence to Voice, must not port browser provider-key persistence, and must not copy the upstream graph `.gitignore` change unless a new AI OS local graph artifact is actually introduced. *** ## 2. Objectives 1. Update Hermes and local API documentation for shipped Phase 40 model, command, MoA, chat, Ministry, compact, context, and voice behavior. 2. Record final not-ported upstream rationale and metadata decisions in one durable closeout ledger. 3. Preserve AI OS package identity, existing package scripts, committed graph seed contracts, and public-demo/local-control-plane privacy boundaries. 4. Validate that changed docs contain shipped-behavior claims only and do not expose private paths, credentials, raw prompts, transcripts, or secret-shaped strings. *** ## 3. Prerequisites ### Required Sessions * [x] `phase40-session01-baseline-and-port-invariants` through `phase40-session15-ministry-config-analytics-and-save-ux` - shipped the model, redaction, chat, command, MoA, catalog, pricing, asset, selector, compact, command UX, Ministry, analytics, and save behavior that docs must now describe. * [x] `phase40-session16-voice-parity-and-broker-respawn` - provides the voice parity evidence and documentation queue for Session 17. ### Required Tools Or Knowledge * `bash .spec_system/scripts/analyze-project.sh --json` output from 2026-07-03 showing Phase 40 in progress, no active session, Sessions 01-16 complete, and Session 17 unfinished. * Current bridge, hook, parser, and component owners for Hermes behavior: `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-admin-bridge.ts`, `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts`, `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, and Hermes component docs in `docs/`. * Phase 40 implementation summaries and Session 16 implementation notes. ### Environment Requirements * Bun 1.3.14 repo-pinned environment for any targeted doc or TypeScript checks run during implementation. * No live Hermes, OpenAI Realtime, OpenRouter, graphify, or upstream checkout credentials are required for this documentation-planning session. *** ## 4. Scope ### In Scope (MVP) * AI OS readers can understand the shipped Hermes local API surface - update local API notes for `/__hermes_model_intelligence`, expanded `/__hermes_chat` options and `info` SSE events, `/__hermes_cmd`, `/__hermes_moa_save`, and `/__start_voice`. * AI OS readers can understand the shipped Hermes page behavior - update README and agent-page docs for model selector, approximate context meter, compact flow, command menu, slash actions, Ministry builder, Ministry analytics, save UX, and voice caveats. * AI OS maintainers can audit final port dispositions - create a Phase 40 closeout ledger that records shipped behavior, intentionally not-ported upstream behavior, package metadata decisions, `.gitignore` decisions, and graph seed preservation rationale. * AI OS privacy boundaries stay accurate - update local voice, Intelligence, data-contract, and handoff docs to state that provider keys remain environment-only, public/demo mode has no live voice or writes, and browser data contains only safe metadata. ### Out Of Scope (Deferred) * New Hermes, Ministry, voice, model, command, Dream, Knowledge Graph, or public-demo product behavior - Reason: Session 17 is documentation and metadata closeout only. * New package scripts, dependency changes, package renaming, or upstream package version migration - Reason: no tested implementation requires metadata changes, and AI OS package identity must be preserved. * Copying upstream graph ignore rules wholesale - Reason: AI OS intentionally commits `src/data/graphs/index.json` and `src/data/graphs/ai-os.json`; only `graphify-out/` is currently generated and gitignored. * Claiming live provider voice proof, Windows scheduler proof, exact tokenizer context reclamation, hosted writes, public product APIs, or Dream engine-selection behavior beyond existing shipped docs - Reason: these claims require matching code and evidence. *** ## 5. Technical Approach ### Architecture Use code and completed session artifacts as the documentation source of truth. The main docs edits should describe the existing split AI OS ownership model: Hermes public reads live in `scripts/lib/hermes-dev-bridge.ts`, local admin writes live in `scripts/lib/hermes-admin-bridge.ts`, browser contracts are parser-owned in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`, and product surfaces consume those contracts through `useHermes()` and `useHermesAdmin()`. The closeout ledger should not replace the PRD or validation report. It should be a durable reader-facing summary under `docs/` that links the shipped Phase 40 behavior to explicit not-ported decisions and metadata outcomes. Documentation must use safe example values, no raw local paths, and no credential-shaped strings. ### Design Patterns * Documentation follows implementation: Update docs only after checking the matching code owner or completed session evidence. * Parser-owned contracts: Refer to typed parser contracts for browser-visible model, command, MoA, and voice payload shapes instead of restating raw bridge internals as product behavior. * No-change metadata rationale: When `.gitignore` and `package.json` should not change, record the rationale in docs rather than creating cosmetic metadata churn. * Product language boundaries: Use AI OS for host/local operator behavior, Hermes Intelligence for the portal, Voice only for speech controls, and Trend Finder only for the extension. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/phase-40-port-closeout.md` | Final shipped-behavior, not-ported, package metadata, `.gitignore`, graph seed, and validation rationale for Phase 40 closeout. | \~170 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/api/README_api.md` | Add shipped Hermes model-intelligence read, chat override/info SSE, command, MoA save, and voice launch contracts with local-only gates. | \~140 | | `README.md` | Refresh Hermes Agent Surface summary for shipped Phase 40 behavior and local-only caveats. | \~60 | | `docs/agent-pages.md` | Update Hermes page current-state details, admin endpoints, Chat/Pantheon/Ministry behavior, and test references. | \~110 | | `docs/data-contract.md` | Add browser-safe Hermes catalog, model-intelligence/pricing, command, MoA save, and voice metadata boundary notes. | \~100 | | `docs/local-voice-setup.md` | Add Session 16 no-reprompt parity, empty launch, no browser provider config, and live-proof caveats. | \~45 | | `docs/intelligence-view.md` | Align portal naming, voice ownership, browser payload shape, and verification limits with Session 16 evidence. | \~45 | | `docs/README_docs.md` | Add the Phase 40 closeout ledger to the docs index. | \~5 | | `docs/ongoing-projects/TODO.md` | Record final Phase 40 not-ported/handoff notes and remove rediscovery risk for shipped Hermes behavior. | \~45 | | `docs/CHANGELOG.md` | Add the Session 17 documentation closeout entry without claiming validation for Session 18. | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Local API docs include the shipped route names `/__hermes_model_intelligence`, `/__hermes_cmd`, `/__hermes_moa_save`, `/__start_voice`, and the expanded `/__hermes_chat` payload/events exactly as implemented. * [ ] User-facing docs describe compact as a summary-and-fresh-chat flow with visible carryover, not exact tokenizer or guaranteed context reclamation. * [ ] User-facing docs describe Ministry as shipped in Pantheon with safe provider assets, analytics provenance, copy fallback, and admin-gated MoA save behavior. * [ ] Voice docs state that AI OS no-reprompt parity is environment-backed broker respawn, not browser OpenAI key persistence. * [ ] Closeout ledger records intentionally not-ported upstream behavior, package metadata no-change rationale, and `.gitignore` graph no-change rationale. ### Testing Requirements * [ ] Targeted docs formatting or Markdown checks run for changed docs, or existing out-of-scope Markdown failures are documented. * [ ] Phrase scans prove changed docs do not newly claim unimplemented Intelligence, voice, Dream, package, graph, hosted, or public API behavior. * [ ] Privacy scans prove changed docs do not contain raw private paths, tokens, auth JSON examples, real-key-shaped strings, prompts, transcripts, raw command output, or provider payloads. ### Non-Functional Requirements * [ ] Documentation remains concise and current-state oriented. * [ ] Public demo, local bridge, scheduler, Dream, Hermes, Knowledge Graph, and Trend Finder data boundaries remain separate. * [ ] No app code, generated private data, dependency, lockfile, or package script changes are introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Documentation uses shipped behavior, not upstream promises. *** ## 8. Implementation Notes ### Working Assumptions * The session is repo-wide documentation rather than package-scoped work: the analyzer reports `monorepo: null`, no packages, and no active package, and the Session 17 stub targets docs and repository metadata across the AI OS repo. * Package metadata should be audited and left unchanged: the Session 17 stub says to preserve AI OS package identity and version, and no Phase 40 Session 17 implementation scope requires a new dependency, package script, or package rename. * `.gitignore` should be audited and left unchanged unless implementation finds a new local graph artifact: the current file already ignores `graphify-out/`, while the Phase 40 stub explicitly says not to copy the upstream graph ignore change over committed AI OS graph seed files. ### Conflict Resolutions * Command endpoint naming: the stub names "command endpoint" generically and some summaries refer to command behavior, but code registers `/__hermes_cmd` in `scripts/lib/hermes-admin-bridge.ts` and the hook calls `/__hermes_cmd`; docs must use `/__hermes_cmd`. * Voice no-reprompt behavior: upstream browser key persistence achieves a similar user outcome, but Phase 40 Session 16 records AI OS parity through environment-backed broker respawn and rejects browser provider config; docs must describe the AI OS implementation, not the upstream storage model. * Graph ignore behavior: upstream graph ignore changes conflict with AI OS committed seed graph contracts. The AI OS interpretation wins because `src/data/graphs/index.json` and `src/data/graphs/ai-os.json` are committed demo-safe fallback data, while `graphify-out/` is the generated local output. ### Key Considerations * Do not add new public product API claims. The local Vite and Hermes routes remain local-dev-only bridge endpoints. * Keep docs free of secret-shaped values. Use short examples such as `key`, `voice-token`, or ``. * Do not label mocked voice/broker tests as live provider proof. * Keep Hermes Intelligence as the portal name and Voice as the speech-control capability name. ### Potential Challenges * Docs may already contain older broad statements: Use targeted replacement and supporting scans rather than broad rewrites. * Global Markdown checks may include historical formatting drift: Prefer targeted checks for changed files and document any unrelated existing failures. * API docs can become too detailed: Keep route names, access gates, payload fields, response shape, and safety behavior; avoid restating implementation internals that can drift. ### Relevant Considerations * \[P00] **Do not document planned features as implemented**: Session 17 is specifically a docs closeout, so every claim must trace to code or completed Phase 40 evidence. * \[P38] **Upstream ports are semantic, not wholesale**: The docs must record semantic AI OS outcomes and skipped upstream paths, not copy upstream wording. * \[P38] **OpenAI Realtime keys stay environment-only**: Voice docs and examples must reject browser-stored provider keys and browser-supplied provider config. * \[P38] **Local control-plane gates are defense in depth**: Local bridge docs must keep loopback, host, token, admin, method, body-size, timeout, and safe error boundaries visible. * \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Docs must preserve static public-demo boundaries and avoid hosted bridge or write claims. *** ## 9. Testing Strategy ### Unit Tests * No production code or parser behavior should change. If implementation discovers a docs change requires code behavior, stop and rescope rather than adding app code inside this session. ### Integration Tests * Run targeted documentation formatting checks for changed Markdown files. * Run targeted phrase scans against changed docs and README for unshipped claims around voice, Intelligence, Dream engine selection, package metadata, public APIs, graph artifacts, and hosted writes. ### Runtime Verification * No live runtime verification is required because this is documentation and metadata closeout. Implementation should rely on completed Session 01-16 validation artifacts and direct source inspection for route and payload names. ### Edge Cases * Existing docs can mention historical Phase 38 or Phase 40 behavior. Preserve history where labeled historical, but make current-state sections explicit. * Existing `.gitignore` and `package.json` may need no diff. The session still succeeds if the no-change rationale is recorded in the closeout ledger. * If `bun run lint:md` fails on unrelated historical docs, record the exact unrelated failure and pass targeted changed-file formatting instead. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase40-session01-baseline-and-port-invariants` through `phase40-session16-voice-parity-and-broker-respawn`. * Depended by: `phase40-session18-full-validation-and-handoff`. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session17-docs-metadata-and-gitignore-closeout/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.