> 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/phase23-session03-non-hermes-parity-documentation-closeout/spec.md). # Session Specification **Session ID**: `phase23-session03-non-hermes-parity-documentation-closeout` **Phase**: 23 - Non-Hermes Routes, Polish And Closeout **Status**: Not Started **Created**: 2026-06-02 *** ## 1. Session Overview This session closes the non-Hermes v2.3 migration by proving that Phase 21 through Phase 23 work is implemented, documented, validated, or explicitly deferred with rationale. It is a closeout session, not a feature session: the main outputs are durable documentation updates, a validation evidence record, and a final statement on whether the old non-Hermes backlog document is still needed as a source of truth. The old `docs/ongoing-projects/v2_3-port-remaining.md` file is already absent from the current repository. That changes the closeout shape: implementation must confirm that the phase PRD, session stubs, implementation notes, and public docs preserve every important source anchor, skip/no-action decision, and residual deferral from the old backlog. This is the natural next Phase 23 session because Sessions 01 and 02 are validated and complete. Session 03 depends on the Claude Code route, UI polish, and optional tooling decisions being finished before final parity validation can be trusted. *** ## 2. Objectives 1. Verify that every Phase 21-23 non-Hermes backlog item is implemented, explicitly deferred, or recorded as no-action with rationale. 2. Update durable developer-facing docs for implemented Phase 23 route and UI changes, especially Claude Code route coverage and agent-page boundaries. 3. Run and record the final validation strategy for sensitive OAuth, local-agent, home-transform, route, polish, docs, and build gates. 4. Produce a final residual-gap and old-backlog source-of-truth decision for Phase 23 handoff to `validate` and then `updateprd`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-pricing-daily-activity-accuracy` - Provides pricing fallback accuracy and real daily session counts. * [x] `phase21-session02-project-windows-skill-roi-defaults` - Provides recent project windows, long-tail project rows, and skill ROI defaults. * [x] `phase21-session03-authoritative-claude-usage-oauth` - Provides the script-only OAuth usage path, redaction, and live/estimate affordance. * [x] `phase22-session01-antigravity-detection-data-contract` - Provides the additive Antigravity detection and live-data contract. * [x] `phase22-session02-antigravity-usage-consumers` - Provides Antigravity usage-panel and home ROI consumers. * [x] `phase22-session03-setup-wizard-dream-sources-strip` - Provides Hermes setup default handling and Dream source-status strip. * [x] `phase23-session01-claude-code-agent-route` - Provides the Claude Code route, sidebar entry, route-tree registration, and route safety tests. * [x] `phase23-session02-ui-polish-optional-local-tooling` - Provides skill card sheen, sticky sidebar polish, launch config, and optional tooling decisions. ### Required Tools/Knowledge * Bun package scripts in `package.json`. * Vitest and Playwright validation conventions in `docs/testing.md`. * Route and agent-page documentation conventions in `docs/route-coverage.md` and `docs/agent-pages.md`. * Security and privacy posture from `.spec_system/SECURITY-COMPLIANCE.md`. * Source anchors and no-action decisions in `.spec_system/PRD/phase_23/PRD_phase_23.md`. ### Environment Requirements * No live OAuth credentials, Hermes runtime, OpenClaw runtime, Antigravity install, or Apify/OpenAI credentials are required. * Browser smoke tests should use the normal Playwright/Vite local server on `127.0.0.1:5189` when run. * If Playwright Chromium is not installed for the active user, record the missing browser binary as an actionable validation gap. *** ## 4. Scope ### In Scope (MVP) * AIOS maintainers can trust the phase closeout - Audit Phase 21-23 session summaries, validations, phase PRDs, and no-action decisions. * AIOS maintainers can find implemented route behavior in docs - Update `docs/agent-pages.md` and `docs/route-coverage.md` for the Claude Code route and current route count. * AIOS maintainers can rerun validation - Update `docs/testing.md` with a practical Phase 21-23 closeout command set if current docs lack one. * AIOS reviewers can see final project history - Update `docs/CHANGELOG.md` with the non-Hermes closeout and residual-gap status. * AIOS reviewers can verify old backlog independence - Record whether any docs still depend on `docs/ongoing-projects/v2_3-port-remaining.md`. * AIOS reviewers can assess residual risk - Record failed or skipped validation commands with actionable notes instead of silently treating them as green. ### Out of Scope (Deferred) * Implementing new Phase 21-23 features - Reason: this session closes and validates existing work. * Deleting the old backlog file - Reason: the file is already absent; this session only confirms whether that absence is safe. * Legal advice or relicensing - Reason: documentation can record existing license posture but cannot provide legal advice. * Re-generating art assets or porting Hermes file-type art scripts - Reason: Session 02 recorded the optional tooling decision. * Hand-editing `src/routeTree.gen.ts` - Reason: route-tree output is generated and Phase 23 route work is already complete. *** ## 5. Technical Approach ### Architecture Use the phase artifacts as the authoritative audit trail, then patch only the durable docs that are stale against current code. The implementation should start with an evidence matrix that maps Phase 21-23 sessions to their source anchors, implemented behavior, validation records, and residual deferrals. Documentation updates should be narrow and fact-based. `docs/agent-pages.md` should describe the implemented Claude Code route as a presentation variant that reuses the Hermes Mission Control data path and admin gate. It must not claim new bridge capabilities. `docs/route-coverage.md` should update the route inventory and route-tree count to include `/agents/claude-code`. Validation evidence should be recorded in implementation notes with exact commands, pass/fail/skipped status, and actionable gaps. Sensitive OAuth checks must remain mocked or script-only; no task should print credential values, token-bearing strings, raw local paths, transcripts, prompts, or generated private data. ### Design Patterns * Audit-first closeout: Build the evidence matrix before editing docs. * Documentation of implemented behavior only: Update docs from current code and session evidence, not planned intent. * Provider-neutral boundaries: Keep Claude Code, Codex, OpenClaw, Antigravity, and Hermes descriptions aligned with `localAgents` and host-cockpit language. * Script-only sensitive paths: OAuth and local runtime validation must keep credential material out of browser state and logs. * Explicit residual gaps: Any failing or unavailable command is recorded with the next owner/action. ### Technology Stack * Bun 1.3.14 for scripts and package commands. * TypeScript 6.0.3 for app and script typechecks. * React 19.2.0, TanStack Router 1.170.4, and Tailwind CSS 4.2.1 for the route surfaces being validated. * Vitest 4.1.6 for focused and full unit/regression tests. * Playwright Chromium for browser route smoke checks when available. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase23-session03-non-hermes-parity-documentation-closeout/implementation-notes.md` | Evidence matrix, docs audit, command results, residual gaps, and old-backlog decision. | \~180 | | `.spec_system/specs/phase23-session03-non-hermes-parity-documentation-closeout/security-compliance.md` | Security and privacy closeout for validation and documentation updates. | \~90 | | `.spec_system/specs/phase23-session03-non-hermes-parity-documentation-closeout/IMPLEMENTATION_SUMMARY.md` | Session closeout summary after implementation. | \~100 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------ | ---------------------------------------------------------------------------------- | ---------- | | `docs/agent-pages.md` | Add Claude Code route documentation and shared Mission Control safety boundary. | \~80 | | `docs/route-coverage.md` | Add `/agents/claude-code`, update route-tree count, and record coverage status. | \~35 | | `docs/testing.md` | Add or refine Phase 21-23 non-Hermes closeout validation commands. | \~45 | | `docs/CHANGELOG.md` | Record Phase 23 non-Hermes closeout and residual-gap status. | \~35 | | `README.md` | Verify and update only if implemented non-Hermes route or closeout docs are stale. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Phase 21-23 evidence matrix maps every relevant session to implemented behavior, validation, or explicit deferral. * [ ] Claude Code route docs state the route is implemented and reuses Mission Control safety boundaries without claiming new bridge capabilities. * [ ] Route coverage inventory includes `/agents/claude-code` and the current route-tree count. * [ ] Docs no longer depend on `docs/ongoing-projects/v2_3-port-remaining.md` as the only source of truth. * [ ] Final notes state whether the absent old backlog file is safe to keep absent. * [ ] Residual validation gaps, if any, are actionable and not hidden. ### Testing Requirements * [ ] Focused Phase 21-23 Vitest suites run and results are recorded. * [ ] Full or agreed quality gates run: typecheck, script typecheck, lint, format check, tests, build, bundle budget, and private artifact check. * [ ] Route/browser smoke checks run as available for home, skills, and agent pages. * [ ] Documentation reference search verifies no stale old-backlog dependency. ### Non-Functional Requirements * [ ] No new credentials, private paths, generated runtime data, or secret-like values are committed. * [ ] OAuth usage remains script-only, null-safe, and redacted. * [ ] Local-agent docs preserve host-cockpit versus Trend Finder extension separation. * [ ] No heavy dependencies, generated assets, or route-tree hand edits are introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Documentation describes implemented behavior, not planned behavior. *** ## 8. Implementation Notes ### Key Considerations * The old backlog file is already absent, so the implementation should verify that this is safe rather than plan a deletion. * `docs/agent-pages.md` currently documents Hermes and OpenClaw; it should be updated for Claude Code now that `/agents/claude-code` exists. * `docs/route-coverage.md` predates the Claude Code route and needs route count and agent-route coverage updates. * `docs/testing.md` has broad validation commands, but a concise Phase 21-23 closeout command cluster will make this final pass reproducible. * Phase 23 Session 02 was already validated; the state repair during planning aligned `completed_sessions` with existing validation artifacts. ### Potential Challenges * Validation suite duration: Mitigate by running focused suites first and then full gates, recording any timeout or environment gap precisely. * Playwright browser availability: Mitigate by recording missing browser installation as an actionable gap instead of treating browser proof as green. * Docs overclaiming safety: Mitigate by tying Claude Code route docs to the existing Hermes Mission Control hooks and admin gate only. * Stale old-backlog references: Mitigate with repository-wide searches and explicit replacement or rationale. ### Relevant Considerations * \[P00] **Do not document planned features as implemented**: Closeout docs must separate shipped behavior from deferred optional tooling and unavailable live-environment proof. * \[P04] **Hermes bridge guardrails must stay intact**: Claude Code route docs must preserve the shared Mission Control safety boundary. * \[P09] **Provider-neutral helpers stay the UI projection layer**: Local-agent closeout should keep provider-specific details behind shared projections. * \[P21] **Claude OAuth material stays script-only**: Validation notes must not expose token-bearing fields, bearer headers, or credential-shaped strings. * \[P22] **Centralize nested local-agent selectors before UI**: Antigravity and Dream source docs should describe sanitized selectors, not raw local data. *** ## 9. Testing Strategy ### Unit Tests * Run focused OAuth, usage, aggregate, Antigravity, Dream source, route, skill card, sidebar, and agent-page Vitest suites. * Prefer existing test files over new tests unless docs audit finds a concrete coverage gap. ### Integration Tests * Run `bun run typecheck`, `bun run typecheck:scripts`, `bun run lint`, `bun run format:check`, `bun run test`, `bun run build`, `bun run budget:check`, and `bun run runtime:check-private`. * Record command output summaries in implementation notes. ### Manual Testing * Search docs and spec artifacts for old-backlog dependencies. * Review `/`, `/skills`, `/agents/hermes`, `/agents/openclaw`, and `/agents/claude-code` route coverage records against current source files. * Run targeted Playwright specs when browser tooling is available. ### Edge Cases * Old backlog file is absent before the session starts. * A validation command fails due to environment setup rather than product code. * Docs mention Claude Code route but imply standalone bridge behavior. * Optional tooling decisions are accidentally converted into required features. *** ## 10. Dependencies ### External Libraries * None added. ### Other Sessions * **Depends on**: Phase 21 Sessions 01-03, Phase 22 Sessions 01-03, Phase 23 Sessions 01-02. * **Depended by**: Phase 23 validation and updateprd closeout; phase transition can begin only after this session is implemented, validated, and marked complete. *** ## Next Steps Run the implement workflow step to begin AI-led 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/phase23-session03-non-hermes-parity-documentation-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.