> 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/phase38-session06-policy-docs-and-catalogs/spec.md). # Session Specification **Session ID**: `phase38-session06-policy-docs-and-catalogs` **Phase**: 38 - Claude OS v2.8.1 Semantic Port **Status**: Not Started **Created**: 2026-06-29 *** ## 1. Session Overview This session aligns AI OS policy, documentation, executable-mode evidence, and Hermes model catalogs with the Phase 38 semantic port after Sessions 01 through 05 have completed. It is next because the deterministic project analysis shows Phase 38 Sessions 01 through 05 complete, no active session, and Session 06 as the first unfinished candidate. The work is intentionally documentation- and catalog-heavy. AI OS must adopt the resolved upstream v2.8.1 license posture, describe only behavior that exists in AI OS, remove stale upstream endpoint language, and preserve current local control-plane security boundaries. Model catalog changes must keep AI OS defaults as the active defaults while exposing upstream model names only when provider readiness can represent them or when the UI labels them as unavailable or explanatory options. Voice broker and Intelligence portal product behavior are not implemented until Sessions 08 and 09. This session may document their current not-yet-shipped status and resolved provider policy, but it must not add a broken voice-lab launch target or claim that voice, Intelligence, or Dream engine selection is already shipped. *** ## 2. Objectives 1. Adopt the resolved upstream v2.8.1 license posture in root legal and package metadata while preserving AI OS attribution and third-party notices. 2. Update README, agent guidance, changelog, runbooks, and setup/development docs so they describe current AI OS endpoints, privacy boundaries, and Phase 38 behavior without stale upstream claims. 3. Preserve AI OS Hermes defaults while adding upstream model names as selectable, readiness-backed, disabled, or explanatory catalog entries with matching tests. 4. Record executable-bit, voice-launch, stale-endpoint, and model-catalog verification evidence for Session 10 reconciliation. *** ## 3. Prerequisites ### Required Sessions * [x] `phase38-session01-tier-0-parity-fixes` - Provides Memory, seed-data, and Hermes graph/yolo parity fixes that docs must describe accurately. * [x] `phase38-session02-platform-foundation` - Provides shared platform helper behavior that Windows and CLI docs can reference. * [x] `phase38-session03-aggregate-and-dream-health` - Provides aggregate and Dream health behavior that docs can reference as shipped. * [x] `phase38-session04-dream-scheduling-and-setup` - Provides Dream scheduler and setup readiness behavior that docs can reference as shipped. * [x] `phase38-session05-runtime-bridge-hardening` - Provides local control-plane Host-header and bridge hardening that docs must preserve. ### Required Tools Or Knowledge * Bun 1.3.14, Vitest, TypeScript, Prettier, ESLint, markdownlint, and `rg`. * Upstream v2.8.1 reference files under `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/`. * Full patch and findings report under `/home/aiwithapex/projects/claudeos/`. * Current AI OS docs, Hermes bridge/catalog modules, and legal files. ### Environment Requirements * Repository root is `/home/aiwithapex/projects/aios`. * No secrets, API keys, bearer headers, token-shaped strings, raw local paths, or generated private data may be added to docs or product fixtures. * Documentation must keep public demo, local bridge, and local-only operator data boundaries explicit. *** ## 4. Scope ### In Scope (MVP) * AI OS maintainers can rely on root legal metadata matching the resolved Phase 38 license posture - update `LICENSE`, `NOTICE`, and `package.json`. * Local operators can follow README, onboarding, development, Dream, and agent guidance without hitting removed upstream endpoints - update docs around `/__run_dream`, `/__refresh_data`, `/__live-data`, `/__token`, and `/__hermes_*` local endpoints. * Future Session 08 and 09 implementers can find truthful voice and Intelligence setup docs - add current-state docs that say the broker and portal are not shipped until those sessions and name the real backend requirements. * Hermes users can see a coherent model catalog - preserve `gpt-5.5` AI OS defaults and add upstream model names only as readiness-backed or clearly unavailable/explanatory options. * Session 10 can reconcile upstream changed paths - record executable mode, missing script, voice launch target, docs sweep, and model catalog evidence. ### Out Of Scope (Deferred) * Adding `.claude/launch.json` `voice-lab` as a runnable target - Reason: Session 08 owns the broker and package script needed for the target to work. * Implementing Dream engine selection or dashboard generation UX - Reason: Session 07 owns durable Dream engine product integration. * Implementing the OpenAI Realtime broker or provider token minting - Reason: Session 08 owns live voice broker behavior and security tests. * Implementing the Intelligence portal or visualizers - Reason: Session 09 owns the portal, real `/__hermes_chat` bridge, voice loop, and visualizer tests. * Copying upstream sidecar/API docs verbatim - Reason: the Phase 38 findings report identifies removed upstream endpoints and stale setup language. *** ## 5. Technical Approach ### Architecture Legal and docs changes should be source-truth updates, not broad marketing rewrites. Use the Phase 38 PRD and Session 06 stub to decide which upstream material is adopted, adapted, or deferred. Root README and agent files should stay concise and point into focused docs where the details are longer. Hermes model catalog work should stay inside the existing Hermes read-only and demo-data contracts. `scripts/lib/hermes-dev-bridge.ts` owns the browser-safe model catalog returned by the local bridge, `src/lib/hermes-demo-data.ts` owns demo fixtures, `scripts/lib/model-helpers.ts` and `scripts/lib/session-scanner.ts` own label and pricing recognition, and Hermes component tests prove the product surface still defaults to AI OS selections. Documentation verification should be repeatable. Use `rg` sweeps for removed upstream endpoints, voice/Intelligence overclaims, stale `claude-os` storage claims, and unverified model-default language. Use `git ls-files -s` for tracked executable bits and record the missing `scripts/webp-file-type-art.sh` disposition instead of reintroducing the script only for mode parity. ### Design Patterns * Docs as behavior contracts: describe what current AI OS can run, and call out later sessions as future implementation without presenting them as shipped. * Compatibility naming: preserve inherited `CLAUDE_OS` and `FINDTREND` names when they are compatibility contracts, but avoid adding new global `findtrend` identifiers. * Browser-safe catalog data: product-facing catalog entries must be labels, providers, tiers, and availability states only, never secrets or auth hints. * Evidence-first planning: every changed upstream policy item gets a recorded disposition or verification note for Session 10. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- | | `docs/local-voice-setup.md` | Current-state voice setup policy, provider defaults, and Session 08 ownership without overclaim. | \~140 | | `docs/intelligence-view.md` | Current-state Intelligence view policy and Session 09 real-backend delivery bar. | \~130 | | `.spec_system/specs/phase38-session06-policy-docs-and-catalogs/implementation-notes.md` | Evidence log for docs sweep, executable modes, catalog policy, and deferred launch disposition. | \~160 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | | `LICENSE` | Adopt resolved upstream v2.8.1 license posture. | \~180 | | `NOTICE` | Preserve AI OS attribution, inherited foundation notice, third-party asset boundaries, and restrictive posture. | \~60 | | `package.json` | Set package license metadata to `SEE LICENSE IN LICENSE`; preserve scripts until Session 08 adds voice script. | \~5 | | `README.md` | Align current endpoints, Windows/setup notes, privacy boundaries, and Phase 38 shipped behavior. | \~120 | | `AGENTS.md` | Update local agent guidance; `CLAUDE.md` and `GEMINI.md` symlinks inherit the pointer. | \~40 | | `docs/CHANGELOG.md` | Add a Phase 38 Session 06 entry for policy, docs, catalog, and verification work. | \~60 | | `docs/onboarding.md` | Align setup, endpoint, privacy, and generated-data guidance with current AI OS behavior. | \~80 | | `docs/development.md` | Align local dev endpoint and Windows notes with Sessions 02 through 05 behavior. | \~80 | | `docs/runbooks/ai-os-dream.md` | Align Dream health/scheduler documentation with shipped Session 03 and 04 behavior only. | \~80 | | `scripts/lib/hermes-dev-bridge.ts` | Add upstream model names to the browser-safe catalog only where readiness or explanatory states support them. | \~60 | | `src/lib/hermes-demo-data.ts` | Keep AI OS defaults and demo fixtures coherent with the expanded model catalog. | \~50 | | `scripts/lib/model-helpers.ts` | Recognize upstream model labels without making unsafe provider or pricing claims. | \~40 | | `scripts/lib/session-scanner.ts` | Preserve pricing defaults and add only verified or family-based recognition for upstream Claude model slugs. | \~40 | | `scripts/lib/__tests__/hermes-dev-bridge.test.ts` | Cover catalog entries, default preservation, and demo-safe response shape. | \~80 | | `src/components/hermes/__tests__/hermes-sections.test.tsx` | Cover Hermes product surfaces with expanded catalog options and unchanged defaults. | \~80 | | `scripts/lib/__tests__/model-helpers.test.ts` | Cover upstream model label recognition and unsafe label handling. | \~60 | | `scripts/lib/__tests__/session-scanner.test.ts` | Cover added Claude model recognition and pricing fallback behavior. | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `package.json` license metadata matches the adopted upstream posture and `NOTICE` remains accurate for AI OS inherited and third-party materials. * [ ] README, agent docs, onboarding, development, and Dream runbooks contain no removed upstream endpoints such as `127.0.0.1:17873`, `/api/install`, `/api/aggregate`, or `/api/dream-now`. * [ ] Docs describe current AI OS endpoints and local-only bridge boundaries without claiming Session 07, 08, or 09 behavior as shipped. * [ ] `.claude/launch.json` voice-lab target disposition is recorded as Session 08-owned unless the broker and script exist during implementation. * [ ] Hermes model catalog surfaces preserve AI OS defaults while upstream model names appear only as provider-ready, disabled, or explanatory options. * [ ] Existing executable files remain tracked as executable and the missing `scripts/webp-file-type-art.sh` disposition is recorded. ### Testing Requirements * [ ] Unit tests written and passing for model helpers, session scanner pricing recognition, Hermes dev bridge catalog output, and Hermes component catalog rendering. * [ ] Docs stale-claim sweeps completed for removed endpoints, unimplemented voice/Intelligence claims, stale storage names, and unverified model defaults. * [ ] Verification scenarios completed for license metadata, executable bits, voice launch target disposition, and docs links. ### Non-Functional Requirements * [ ] Documentation remains concise, current-state oriented, and free of secret patterns or generated private local data. * [ ] Model catalog additions do not introduce new dependencies, network calls, remote code loading, or browser-visible provider credentials. * [ ] Legal and README language avoids calling the project open source after adopting the resolved restrictive license posture. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] `bun run lint`, `bun run typecheck`, `bun run typecheck:scripts`, and targeted tests pass or exact unrelated blockers are recorded. *** ## 8. Implementation Notes ### Working Assumptions * Current-state voice and Intelligence docs are safer than omitting the docs: the Session 06 stub includes voice and Intelligence documentation targets, while also saying not to claim unimplemented behavior. It is safe to proceed by documenting that the broker and portal are not shipped until Sessions 08 and 09 and by naming their delivery bars. * The root agent docs are represented by `AGENTS.md`, with `CLAUDE.md` and `GEMINI.md` symlinked to it. Updating `AGENTS.md` satisfies the agent-doc target without replacing the symlinks. * The current changelog owner is `docs/CHANGELOG.md`, not a root `CHANGELOG.md`. Adding the Session 06 entry there preserves the repo's existing phase-log pattern and satisfies the changelog deliverable. ### Conflict Resolutions * Session 06 lists `.claude/launch.json` voice-lab target work, but its detailed launch target section says to port the target alongside Session 08 voice broker. The chosen interpretation is to record the target disposition now and leave the runnable launch target to Session 08, because adding it before the broker exists would create a broken command. * Upstream docs include voice sidecar, removed sidecar API endpoints, and broad setup claims. The chosen interpretation is to adapt only the policy and privacy language that matches AI OS and to reject stale endpoint claims, because the Phase 38 findings report explicitly warns against copying those docs verbatim. * Upstream model names are not independently verified. The chosen interpretation is to keep current AI OS defaults and expose new names only as readiness-backed, disabled, or explanatory options, because the Phase 38 PRD makes that the resolved model catalog policy. ### Key Considerations * License posture changes may affect README language, package metadata, and public docs wording; update these together. * Docs must keep public demo, local bridge, local scheduler, Dream, Hermes, and Trend Finder data boundaries separate. * Session 10 needs exact evidence, so implementation notes should capture commands, sweeps, executable modes, and unresolved future-session ownership. ### Potential Challenges * Restrictive license text may conflict with old README wording: revise README around terms and distribution instead of weakening the adopted license. * Model catalog contracts may not currently encode disabled entries: if so, use explanatory group labels or provider-readiness copy without adding a larger contract change than the session needs. * Markdown lint may surface pre-existing issues: record exact unrelated blockers, but fix scoped issues introduced by this session. ### Relevant Considerations * \[P01] **Old `claude-os-*` naming**: Preserve compatibility names only where they are existing contracts; do not add new `findtrend` globals. * \[P02] **Extension payloads and labels stay bounded**: Model catalog and docs updates must stay browser-safe and avoid secret/provider credential exposure. * \[P21] **Claude OAuth material stays script-only**: Do not expose auth material or bearer-shaped strings in docs, fixtures, logs, or browser state. * \[P34-P37] **AI Rogue is production default-enabled**: README and docs must preserve the current production-default extension posture. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Documentation overclaims future voice, Intelligence, or Dream engine behavior before it is implemented and proven. * Model catalog entries become active defaults or product promises even when provider readiness cannot represent them. * Legal metadata changes omit AI OS attribution or leave README language that contradicts the adopted license posture. *** ## 9. Testing Strategy ### Unit Tests * Test Hermes dev bridge model catalog output, default preservation, and browser-safe response shape. * Test Hermes component rendering with expanded catalog options and unchanged selected defaults. * Test model helper label normalization for upstream model names and unsafe labels. * Test session scanner recognition or fallback behavior for new Claude model slug families. ### Integration Tests * Run docs sweeps with `rg` for removed upstream endpoints, unimplemented voice/Intelligence claims, stale storage names, and contradictory license wording. * Run executable mode checks with `git ls-files -s` for existing upstream mode-change files. * Run markdown formatting or linting for changed docs where practical. ### Runtime Verification * Verify `/__run_dream`, `/__refresh_data`, `/__live-data`, `/__token`, and `/__hermes_*` references in docs match current AI OS code or existing runbooks. * Verify `.claude/launch.json` still contains only runnable targets unless Session 08 broker support lands in the same implementation window. ### Edge Cases * Docs mention inherited `CLAUDE_OS` compatibility names without presenting them as new identifiers. * Public-demo docs do not imply hosted bridge, collector, or write behavior. * Model labels with unsafe characters remain rejected or marked unsafe. * Missing upstream `scripts/webp-file-type-art.sh` is recorded without recreating a script that AI OS does not use. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase38-session01-tier-0-parity-fixes`, `phase38-session02-platform-foundation`, `phase38-session03-aggregate-and-dream-health`, `phase38-session04-dream-scheduling-and-setup`, `phase38-session05-runtime-bridge-hardening` * Depended by: `phase38-session07-dream-engine-product-integration`, `phase38-session08-voice-broker`, `phase38-session09-intelligence-portal`, `phase38-session10-hunk-reconciliation-and-release-gate` *** ## 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/phase38-session06-policy-docs-and-catalogs/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.