> 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/considerations.md). # Considerations > Institutional memory for AI assistants. Updated between phases via carryforward. **Line budget**: 600 max | **Last updated**: Phase 40 (2026-07-03) *** ## Active Concerns Items requiring attention in upcoming phases. Review before each session. ### Technical Debt * \[P01] **Old `claude-os-*` naming**: Compatibility aliases such as `VITE_CLAUDE_OS_*`, `CLAUDE_OS_*`, `"claude-os"` literals, and `~/.claude-os/` paths still exist. * \[P41] **Local access default migration**: Local AI OS operator goals now default to full access, write access, and edit access. Legacy route names, copy, tests, and env gates that present local Hermes, Knowledge Graph, Claude Code, OpenClaw, Voice, or Intelligence as limited-access by default must be migrated or labeled as implementation gaps. * \[P15] **Scoped scheduler jobs remain deferred**: `agent-aggregate`, scoped Trend Finder refresh, cross-job validation, timers, and final scheduler docs still need a dedicated phase. * \[P26] **Knowledge Graph contract alignment**: Seed data, read/admin bridges, route UI, home summary, and Hermes grounding share one graph contract; schema changes must move together. * \[P35/P39] **AI Rogue compatibility and content gates remain**: Legacy runtime re-exports plus level, save-ID, asset, audio, boss, and finale contracts must stay covered before future content expansion. * \[P38/P40] **Environment-limited proof stays bounded**: Windows Task Scheduler, live Realtime voice, and local-admin MoA save proof require target hosts, credentials, or writable admin state before docs can claim live success. ### External Dependencies * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints. * \[P21] **Anthropic OAuth contract can drift**: Claude CLI availability, credential shape, and usage endpoint behavior must stay optional with estimate fallback. * \[P28/P29] **Trend Finder source scope is narrow**: Approved direct sources remain arXiv, GitHub search, reviewed RSS, and HN Algolia; podcasts, broad social, and new adapters need source-specific compliance and parser tests. * \[P38/P40] **OpenAI Realtime keys stay environment-only**: Voice broker credentials must never come from browser bodies, argv, docs, fixtures, generated data, or browser storage; `OPENAI_BASE_URL` stays restricted to OpenAI or loopback-compatible targets. * \[P40] **Production infra proof is external**: Worker production health, Cloudflare WAF ruleset verification, and GitHub Actions deploy execution need external URLs, dashboard/Terraform access, or Cloudflare secrets before production claims. ### Performance / Security * \[P02] **Extension payloads and labels stay bounded**: Keep the shared 1 MB payload limit and explicit live, fixture, fallback, degraded, blocked, and unavailable states. * \[P11] **Scheduler state/log privacy boundary**: Status surfaces may expose only labels, statuses, durations, exit codes, warnings, lock outcomes, and freshness metadata. * \[P21] **Claude OAuth material stays script-only**: Token-bearing fields, bearer headers, and credential-shaped strings must stay out of browser state, logs, and generated data. * \[P31-P40] **Public-demo and hosted-surface gates stay bundled**: Run fixture/dist privacy scans, no-bridge checks, hosted metadata, static-only assertions, asset checks, browser proof, and bundle budgets together; Phase 40 raised the aggregate JS gzip cap to 1,600 KB while preserving per-file caps. * \[P38/P40] **Local control-plane gates are defense in depth**: Privileged `/__*` routes must preserve socket loopback, Host-header, token/admin, method, body-size, schema, timeout, safe-error, redaction, and no-shell argv checks. ### Architecture * \[P02] **Static extension registry requires code changes**: No marketplace, dynamic loading, eval, or remote code; adding an extension means updating client and script registries. * \[P15] **Full aggregate remains the compatibility command**: Future scoped jobs should call host/local or extension orchestration helpers; do not repurpose `bun run aggregate` into a partial writer. * \[P25] **Mission Control writes stay on the shared admin contract**: Hermes and Claude Code variants share `useHermesAdmin().missions`; route-specific execution or workspace writes need a new threat model. * \[P31-P40] **Pages demo stays static-only**: Public demo work must use committed fixtures and static Pages output; no `/__*` bridge calls, hosted writes, collectors, analytics, Functions, advanced Workers, or local-control-plane APIs without a new threat model. * \[P38/P40] **Upstream ports are semantic, not wholesale**: Map upstream hunks into AI OS module owners, keep route shells thin, preserve package/graph/media identity, and record intentionally skipped upstream behavior. *** ## Lessons Learned Proven patterns and anti-patterns. Reference during implementation. ### What Worked * \[P02] **Static registry over dynamic loading**: Compile-time imports keep type safety, tree-shaking, and no remote-code surface. * \[P05] **Script-only runtime boundary**: Auth, transport, analyst, scoring, snapshot, and source helpers stay under `scripts/lib/` or `scripts/extensions/`. * \[P26] **Parser-backed graph contracts scale well**: One typed parser for seed data, bridge responses, and UI state kept malformed graph payloads out of every surface. * \[P28] **Docs-first source activation scales**: Direct adapters were safer when compliance docs specified approved fields, readiness, fallback, spend behavior, and leak checks before code activation. * \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade; split run factory, snapshots, renderer bridge, world, and type owners behind the narrow runtime barrel. * \[P30/P32/P34-P35] **Schema-backed browser-local state works**: Zod defaults/migrations, schema-owned claim parsing, non-throwing saved-run hydration, and write-boundary guards keep localStorage/IndexedDB saves safe. * \[P30/P34-P40] **Visibility gates catch real issues**: Pair type/lint/format, focused unit/browser tests, build/budget, private-runtime, privacy scans, no-bridge checks, provenance, browser proof, Pages, playthrough, human review, and D3 scans before widening visibility. * \[P31/P33] **Static public-demo projection scales**: `VITE_AI_OS_PUBLIC_DEMO`, exporter-owned allowlists, count summaries, field policies, and Pages dist assembly let real routes deploy without local runtime reads. * \[P31-P33] **Route smoke is a privacy gate**: Desktop/mobile route matrix, product-surface checks, hosted metadata, one real interaction, and no `/__*` assertions catch bridge leaks that unit tests miss. * \[P37] **Manifest-first visual assets scale**: Record accepted and rejected crops before packing, enforce typed required-frame tests, and use browser proof because atlas JSON alone does not prove runtime readability. * \[P38] **Injected platform helpers scale cross-platform work**: Platform/path/env injection let Windows, macOS, and Linux branch behavior be tested from POSIX without mutating process globals. * \[P38] **Narrow config owners prevent product drift**: Dream engine selection stayed coherent because setup, dashboard, scheduled runs, and manual runs shared one typed config owner. * \[P39] **Typed content registry scales level authoring**: Keep level intent in `runtime/content/` and derive depth, objective, finale, asset, audio, and save parity checks from source-owned contracts. * \[P40] **Parser-owned Hermes contracts scale ports**: Model bodies, command responses, MoA save results, chat `info` events, pricing provenance, and connection rows stayed safe because bridge output, parser tests, hooks, and UI fixtures moved together. * \[P40/P41] **Write safeguards are reusable**: Command and MoA save work stayed bounded by reusing loopback/token checks, exact payload validation, no-shell argv or structured YAML writes, atomic backup/replace, and sanitized errors. Keep those safeguards while removing manual admin opt-in posture from local product goals. ### What to Avoid * \[P00/P40] **Do not document planned or environment-limited behavior as implemented**: Docs must track actual behavior, especially live provider proof, public APIs, exact context reclamation, Dream engine selection, and Trend Finder source scope. * \[P41] **Do not accept scaffolding as delivery**: A shipped local feature must execute the intended user outcome, show visible results, expose recovery paths, and have tests. Labels, disabled buttons, unsupported preflights, and mock-only proof are not complete delivery. * \[P02] **Do not expose secret env values through `VITE_` variables or browser state**: Key names and presence booleans are the safe browser boundary. * \[P05] **Do not let source activation happen after collection starts**: Compliance checks belong in declaration and config layers. * \[P11] **Do not mirror scheduler internals or wire scoped jobs early**: Keep scheduler state command-only unless a browser-safe contract exists. * \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Keep Claude OAuth material script-only and redacted. * \[P26] **Do not parse raw graph bridge payloads inside components**: Keep normalization, fallback selection, and browser-safe projection in shared helpers. * \[P30/P32/P34-P39] **Do not widen AI Rogue capabilities without review**: Production visibility, local audio, Phase 37 visuals, and the Phase 39 four-level authored run are approved; collectors, WebGPU, workers, remote loading, hosted writes, saved audio state, new content classes, or rejected-art reuse need fresh review. * \[P31-P40] **Do not let public demo become live runtime**: Pages builds must not run `demo:snapshot`, call `/__*`, read local data, add Functions, host collectors, expose setup labels, enable public writes, or ignore aggregate bundle growth. * \[P38/P40] **Do not copy upstream monoliths or browser-credential patterns**: Upstream route files, Vite middleware, graph ignores, package metadata changes, and browser provider-key persistence are evidence to translate, not files or policies to copy. * \[P38/P40] **Do not turn harnesses into live-proof claims**: Faithful tests are useful evidence, but real Windows scheduler, live Realtime provider, and local-admin MoA write proof require the matching host, credentials, or writable local state. ### Tool/Library Notes * \[P02/P34-P35/P39/P40] **Zod and parser-owned entry points**: Additive defaults, schema-owned claim parsing, durable saved-run hydration, parser-owned ID parity, duplicate-write guards, and strict bridge response parsers keep browser-local writes from drifting. * \[P29/P40] **Reference mode phrase tests are release guardrails**: Add phase-specific phrases for shipped behavior, deferred sources, non-goals, live-proof limits, and no-raw-output boundaries whenever docs are part of release closeout. * \[P30/P32/P34-P37] **PixiJS v8 route, failure, input, audio, and visual tests**: Use strict-CSP renderer checks, WebGL pixels, DOM rects, mount-failure tests, frame-name leak checks, visual/audio proof, mobile/touch contexts, route cleanup, and no-bridge smoke. * \[P31/P33/P35/P40] **TanStack Start Pages output needs isolated preview**: Demo mode skips the Worker plugin and assembles static Pages output; use route smoke, privacy scans, source-owned classification, and both per-file and aggregate JS gzip budgets. * \[P38/P40] **Pure helper tests for local control planes**: Keep Host-header, loopback, CLI resolution, provider-base allowlists, no-shell probes, structured YAML writes, and platform path behavior in pure helpers so endpoint wiring can stay thin and guarded. *** ## Resolved Recently closed items (buffer - rotates out after 2 phases). | Phase | Item | Resolution | | ----- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | P38 | Voice and Intelligence deferral | Session 08 shipped the local Realtime broker and Session 09 shipped the Hermes Intelligence portal with tests and docs. | | P38 | Dream engine selection gap | Setup, dashboard, scheduled runs, and manual runs now share guarded AI OS Dream engine config and product recovery states. | | P39 | AI Rogue level authoring gap | Four authored levels, registry-owned depth, save-ID parity, derived asset/audio gates, boss/finale contracts, docs, and proof passed. | | P40 | Claude OS v2.10.1 Hermes port | Expanded Hermes model, chat, command, MoA, connection, Ministry, voice-parity, asset, docs, and validation behavior shipped in AI OS owners. | | P40 | Public demo aggregate JS budget failure | Validation raised the aggregate JS gzip cap to 1,600 KB with docs; production and Pages budget checks now pass at 1,579 KB. | *** *Auto-generated by carryforward. Manual edits allowed but may be overwritten.* --- # 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/considerations.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.