Agent guide

This repository is designed so an agent can make a narrow, verifiable change without reconstructing the architecture from historical plans.

Read by task

Task	Read first	Code authority
UI or visual change	Design system	src/app/globals.css, src/components/ui
New course	Adding a course	src/course-os/schema/course.ts, loadCourse.ts
Course content	Learning blocks	src/course-os/registry/blockRegistry.ts, src/blocks
New block capability	Learning blocks + Course OS design	src/course-os/registry/blocks.ts, adjacent block definitions
Course routing	Adding a course	src/course-os/services/routes.ts, resolveCoursePath.ts
Search/progress/review	Course OS design	corresponding src/course-os/services directory
Direct course editor	Direct course editing	src/course-os/ui/editor, src/course-os/editor, src/app/api/course-editor
Accounts or personal sync	Accounts and sync	src/auth, src/sync, supabase
Workspace panes, tabs, docking	Design system	src/dockable-workspace (model, ui, persistence, plugins)
Native extension runtime	Plugin SDK	src/plugins/native

Do not read every historical plan by default. Start with the living guide, inspect the linked contract, then inspect one existing example closest to the requested change.

Source-of-truth order

When sources disagree, use this order:

1. Schemas, parsers, registries, and tests.
2. Living guides linked from the documentation hub.
3. Current components and course examples.
4. Historical specifications under docs/superpowers/specs.
5. Historical implementation plans under docs/superpowers/plans.

Report and fix a documentation mismatch instead of silently choosing one version.

Repository invariants

• A course is data plus catalog registration, not a new application.
• All courses use the generic route and the same six universal sections.
• Course data is serializable and does not import UI, hooks, storage, or Next.js routes.
• Blocks own validation, rendering, search extraction, capabilities, and optional mastery behavior.
• Canonical course URLs come from route helpers.
• Progress is event-based and platform-owned; blocks and courses do not write directly to localStorage.
• The application uses one Inter font stack and semantic design tokens.
• Shared form controls and interaction patterns go through src/components/ui.
• Existing IDs and storage semantics are compatibility boundaries.
• Workspace behavior lives in src/dockable-workspace. Adding a course never adds a workspace registration: a course reaches the workspace through the shared core view types and route helpers, and a course-specific pane, renderer, or layout rule is a bug.
• Extensions mutate the layout only through the approved workspace.layout capability, and only for their own panes and the documented core allowlist.
• Direct editing is owner-only and Blob-course-only. Preserve the immutable manifest-last publisher, stable retry ids, alias/identity propagation, and recoverable local draft on every failure path.
• Anonymous study must remain fully functional. Account partitions may sync durable personal documents, but workspace panes/tabs/splits and retry internals remain device-local.
• Extension versioning is mandatory: whenever modifying or updating an extension (manifest, UI, scripts, or styles), always increment its package version in manifest.json (semver: patch for fixes, minor for features/UI updates) and re-pack the .tuesh bundle with npm run pack:plugin so revision digests and archives never drift.

Working protocol

1. Locate the contract. Read the task-specific guide and enforcing code.
2. Find the nearest example. Prefer src/courses/fixture for a small course contract and an existing production course for scale.
3. Make the narrowest coherent change. Do not introduce course-specific architecture to solve a content problem.
4. Validate early. Run the narrowest relevant test before the full gate.
5. Review user-visible behavior. For UI/content work, inspect routes, themes, keyboard behavior, and narrow layouts.
6. Update living documentation. If a public contract, workflow, token, or block shape changed, update its guide in the same change.

Verification matrix

Change	Minimum automated verification
Documentation only	Check relative links and examples against current source
Course content	npm run validate:content
Course registration or Course OS	npm run validate:content and relevant Vitest files
UI primitive or token	npm run typecheck and npm run test
Extension or plugin	Bump version in manifest.json, run npm run pack:plugin, and run plugin tests (vitest run src/plugins/)
Cross-cutting change	npm run check

Automated checks are the floor. A passing suite does not prove visual hierarchy, mobile navigation, source accuracy, or useful alt text.

Completion report

An agent handoff should state:

• The user-visible outcome.
• The files or contracts changed.
• Verification performed and its result.
• Any source gaps, unsupported content types, or follow-up work that remains.

Avoid reporting a course as complete when source material is missing. Model missing documents with available: false and call out the gap.