# CMS-aiChemist Architecture

## 1. System Overview

CMS-aiChemist is a multi-project orchestration system for visual design and frontend work. The architecture employs a hub-and-spoke model with NotebookLM as the orchestration brain and Claude Code as the execution hands.

**Core principle**: NotebookLM is the primary memory, context store, and decision authority. Claude Code is an ephemeral executor that reads context from NotebookLM sources, performs work, and writes results back. Durable knowledge, specifications, decisions, feedback, and architectural state belong in NotebookLM. Claude Code's context window is not persistent memory.

**Session protocol**:
1. PULL - Start by reading NotebookLM sources (via local `handoffs/` mirror or API)
2. EXECUTE - Perform implementation work grounded in NotebookLM context
3. PUSH - Write new learnings, decisions, architectural changes, and feedback back to NotebookLM

**Milestone/decision loop**:
1. QUERY the brain (via `ops/brain/brain-query.sh` or Gemini bridge)
2. Proceed autonomously based on brain guidance (HITL only for destructive/wasteful/regressive changes)
3. DEPLOY to production (rebuild and restart after commits affecting production surfaces)
4. SCREENSHOT during frontend testing (save to `static-site/screenshots/` or `handoffs/screenshots/`)
5. PUSH status update back to NotebookLM

The platform is designed to work across ANY existing/new/future projects, not just a single tool. Pilots test the flow on specific projects, but the architecture and tooling must remain project-agnostic.

## 2. Hub-and-Spoke Model

NotebookLM sits at the center as the brain, with specialized systems as spokes:

```mermaid
flowchart TD
    N[NotebookLM<br/>Brain/Memory/Specs/Decisions] --> O[Claude Code<br/>Execution Core]

    GH[GitHub<br/>Repos/Issues/PRs/Reviews] <--> O
    P[Penpot<br/>penpot.chem.dev<br/>Approved Design/Tokens] <--> O
    E[EmDash<br/>CMS/Content Ops] <--> O
    GR[GitReport<br/>Operational Metrics] <--> O
    S[Stitch<br/>Design Ideation] --> P

    O --> CSA[CSA Pipeline<br/>~/Documents/CSA/<br/>Delivery Artifacts]
    GH --> ADW[ADW Pipeline<br/>~/apps/agent-issue-hook/<br/>Work Intake]
    ADW --> O
```

**Key principle**: Each system has one authoritative responsibility.

| System | Authoritative Responsibility |
|--------|------------------------------|
| NotebookLM | Research/specs/decisions |
| GitHub | Repositories/issues/PRs/reviews |
| Penpot | Approved design/tokens |
| EmDash | Content structures |
| GitReport | Operational truth |
| CSA Pipeline | Delivery artifacts |
| ADW Pipeline | Work intake |

**NotebookLM integration**:
- Account: jonathan@noboxai.com
- Project: noboxAI (gen-lang-client-0069303419, number 253500002207)
- Notebook: CMS-aiChemist (7d8b1917-4466-4f33-b5cf-7a8fb283f160)
- API base: https://us-discoveryengine.googleapis.com/v1alpha/projects/253500002207/locations/us
- Auth: OAuth via `/home/jgatlit/google-cloud-sdk/bin/gcloud auth print-access-token`
- Local mirror: `/home/jgatlit/apps/CMS/handoffs/`
- Brain scripts: `ops/brain/brain-query.sh`, `ops/brain/brain-push.sh`, `ops/brain/brain-status.sh`

## 3. Repository Structure

```
/apps
  /web/                    # Next.js 15 application surfaces
  /cms-theme/              # Astro 6 + EmDash theme surfaces

/packages
  /ui/                     # Shared component primitives (9 components)
  /tokens/                 # DTCG pipeline (171 tokens)
  /schemas/                # Shared content and validation schemas
  /agents/                 # ADW prompts, policies, adapters
  /csa/                    # CSA templates and artifact generators

/design
  /exports/                # Approved Penpot export bundles
  /tokens/                 # Raw and transformed token outputs

/handoffs/                 # Local mirror of NotebookLM sources

/docs
  /architecture/
  /decision-records/

/ops
  /brain/                  # NotebookLM integration scripts
  /sync-static.sh          # Static site sync script

/.github
  /workflows/
    ci.yml                 # Build and smoke test pipeline

/static-site/              # Static file server content (tokens, handoffs, design, docs)

/ecosystem.config.cjs      # PM2 configuration for cms-web and cms-content
```

**Current implementation status**:
- 9 shared components: Button, Card, Tabs, Alert, PricingTable, TestimonialWall, MetricsPanel, AuthorBioCard, FeatureComparisonTable
- 171 DTCG tokens in `packages/tokens/src/tokens.json`
- 9 Next.js routes: / /dashboard /design-system /kaleido-life /pricing /testimonials /metrics /authors /compare
- 2 Astro pages in cms-theme (pilot content)

## 4. Token Pipeline

The token pipeline transforms Penpot design tokens into consumable CSS custom properties.

```mermaid
flowchart LR
    P[Penpot<br/>penpot.chem.dev] -->|Export| J[DTCG JSON<br/>packages/tokens/src/tokens.json]
    J -->|build.py| CSS[CSS Custom Properties<br/>packages/tokens/output/tokens.css]
    J -->|build.py| FLAT[Flat JSON<br/>packages/tokens/output/tokens.json]
    CSS -->|Import| WEB[Next.js<br/>apps/web/]
    CSS -->|Import| CMS[Astro<br/>apps/cms-theme/]
```

**Transform process** (via `packages/tokens/build.py`):
1. Read DTCG JSON from `src/tokens.json` (W3C Design Token Community Group format)
2. Flatten nested token groups into flat key-value pairs
3. Resolve token references (e.g., `{color.primary.base}` to `var(--color-primary-base)`)
4. Convert DTCG types to CSS-compatible values:
   - shadow tokens: `offsetX offsetY blur spread color`
   - cubicBezier tokens: `cubic-bezier(x1, y1, x2, y2)`
   - primitive tokens: pass-through with reference resolution
5. Generate CSS custom properties in `:root` selector
6. Generate flat JSON map for programmatic access

**Token families** (current):
- `color.*` - palette, primary, secondary, success, warning, error, info
- `components.button.*` - button variants (primary, secondary)
- `components.card.*` - card containers
- `components.alert.*` - alert variants (success, warning, error, info)
- `components.pricingCard.*` - pricing table tiers
- `components.testimonial.*` - testimonial cards
- `components.metricsPanel.*` - metrics dashboard
- `components.authorBio.*` - author profile cards
- `components.comparisonTable.*` - feature comparison tables

**Token count**: 171 tokens (grew: 94 to 109 to 121 to 133 to 145 to 158 to 171)

**Build command**:
```bash
cd packages/tokens
python3 build.py
# Outputs:
#   output/tokens.css    (CSS custom properties)
#   output/tokens.json   (flat JSON map)
```

## 5. Component Architecture

Shared component primitives in `packages/ui/` use BEM-style CSS classes (ac- prefix) and consume tokens via CSS custom properties.

**Component metadata** (16-field specification in `component-meta.ts`):
- `component_name` - Component identifier
- `github_issue_refs` - Linked GitHub issues
- `design_asset_id` - Penpot reference
- `component_family` - Category (action, layout, navigation, feedback, data-display)
- `description` - Purpose and token usage
- `supported_framework_targets` - Next.js, Astro/EmDash, or both
- `props_schema` - TypeScript prop interface
- `state_matrix` - Supported states (default, hover, active, focus, disabled, loading, empty, error)
- `a11y_requirements` - Accessibility requirements (WCAG 2.1 AA)
- `responsive_rules` - Breakpoint behavior
- `motion_rules` - Animation/transition specifications
- `content_slots` - Content injection points
- `cms_bindings` - EmDash field mappings
- `token_dependencies` - Required CSS custom properties
- `test_cases` - Verification criteria
- `artifact_communication_notes` - CSA delivery notes

**Export pattern** (from `packages/ui/src/index.ts`):
```typescript
export { componentRegistry } from "./component-meta";
export type { ComponentMeta } from "./component-meta";

export { Button } from "./components/Button";
export type { ButtonProps } from "./components/Button";
// ... (9 components total)
```

**CSS architecture**:
- BEM-style naming: `.ac-button`, `.ac-button--primary`, `.ac-button--disabled`
- Token consumption via CSS custom properties: `var(--components-button-primary-background)`
- No framework-specific styling libraries (pure CSS + tokens)
- Responsive via media queries and token-driven breakpoints

**Framework targets**:
- Next.js: React components with `use client` directive for interactive components
- Astro: Same components imported and rendered server-side or hydrated client-side

## 6. Deployment Topology

Production infrastructure uses PM2 process manager, Caddy reverse proxy, and automatic TLS.

```mermaid
flowchart LR
    DNS[cms.chem.dev] --> C[Caddy<br/>Auto TLS<br/>Reverse Proxy]
    DNS2[cms-content.chem.dev] --> C
    DNS3[cms.chem.dev/ref/] --> C

    C -->|:3500| PM2W[PM2 cms-web<br/>Next.js 15]
    C -->|:3501| PM2C[PM2 cms-content<br/>Astro 6 + EmDash]
    C -->|file_server| STATIC[static-site/<br/>tokens/handoffs/design/docs]

    PM2W --> WEB[apps/web/.next]
    PM2C --> CMS[apps/cms-theme/dist]
```

**PM2 configuration** (`ecosystem.config.cjs`):
```javascript
{
  apps: [
    {
      name: 'cms-web',
      script: 'node_modules/next/dist/bin/next',
      args: 'start --port 3500',
      cwd: '/home/jgatlit/apps/CMS/apps/web',
      instances: 1,
      exec_mode: 'fork',
      autorestart: true,
      max_memory_restart: '256M',
      env: { NODE_ENV: 'production', PORT: 3500 }
    },
    {
      name: 'cms-content',
      script: './dist/server/entry.mjs',
      cwd: '/home/jgatlit/apps/CMS/apps/cms-theme',
      interpreter: '/home/jgatlit/.local/share/fnm/node-versions/v22.22.2/installation/bin/node',
      instances: 1,
      exec_mode: 'fork',
      autorestart: true,
      max_memory_restart: '256M',
      env: { NODE_ENV: 'production', PORT: 3501, HOST: '127.0.0.1' }
    }
  ]
}
```

**Caddy configuration**:
- Automatic TLS via Let's Encrypt
- HTTP/2 and HTTP/3 support
- Compression (gzip, zstd)
- Security headers
- JSON access logging

**Deployment workflow**:
1. Build production bundle: `cd apps/web && npx next build`
2. Restart PM2 process: `pm2 restart cms-web`
3. Verify: `curl -I https://cms.chem.dev/`

**Static sync** (`ops/sync-static.sh`):
- Syncs tokens, briefs, handoffs, docs to `static-site/`
- Served at `https://cms.chem.dev/ref/`
- Browsable file server via Caddy `file_server browse`

**Production URLs**:
- https://cms.chem.dev/ - Next.js application surfaces
- https://cms-content.chem.dev/ - Astro/EmDash CMS surfaces
- https://cms.chem.dev/ref/tokens/ - Token documentation
- https://penpot.chem.dev - Penpot design system (no regression)

## 7. CI/CD

GitHub Actions workflow in `.github/workflows/ci.yml` provides automated build verification and smoke tests.

**Jobs**:
1. `build-web` - Build Next.js application
   - Type-check UI package
   - Build production bundle
   - Runs on: pull_request, push to master
2. `build-cms-theme` - Build Astro application
   - Build production bundle
   - Runs on: pull_request, push to master
3. `smoke-tests` - Playwright smoke tests
   - 12 tests covering all 9 routes
   - Only runs on push to master (after builds pass)

**Build matrix**:
- Node.js: 22
- pnpm: 10
- Browsers: Chromium (via Playwright)

**Status checks**:
- Build pass/fail reported to PR
- Smoke tests only run post-merge
- No branch protection rules enforced yet (defined but not activated)

**Current gaps**:
- No lint/format checks in CI
- No component unit tests in CI
- No visual regression tests
- No design drift monitoring (comparison of implementation vs Penpot artifacts)
- Branch protection rules defined but not enforced on GitHub

## 8. Integration Points

### Penpot MCP
- Server: `@zcubekr/penpot-mcp-server`
- Config: `~/.claude.json`
- API URL: https://penpot.chem.dev
- Access token: 342 chars, ends `...vkGw`
- Usage: Token export, frame inspection, component documentation

### Stitch MCP
- Server: `@_davideast/stitch-mcp proxy`
- Config: `~/.claude.json`
- API key: In `.env` as `STITCH_API_KEY`
- Usage: Generative design ideation (350/mo standard mode, 50/mo experimental)
- Promotion rule: Stitch outputs are proposal material; approved concepts move to Penpot

### EmDash SQLite Adapter
- Location: `apps/cms-theme/data.db`
- Connection: `{ url: "file:./data.db" }`
- Schema: Version "1", collections array format
- Reserved field slugs: id, slug, status, author_id, primary_byline_id, created_at, updated_at, published_at, scheduled_at, deleted_at, version, live_revision_id, draft_revision_id
- Field types: string, text, number, integer, boolean, datetime, select, multiSelect, portableText, image, file, reference, json, slug

### NotebookLM Brain (ops/brain/)
- `brain-query.sh` - Multi-source grounded Q&A via Gemini 2.5 Flash
- `brain-push.sh` - Push new sources to NotebookLM API
- `brain-pull.sh` - Pull sources from NotebookLM API to local mirror
- `brain-status.sh` - List notebooks and sources
- Bridge pattern: Read local mirrors, send to Gemini API with grounding, get source-grounded answers
- Query model: `gemini-2.5-flash` via `generateContent` endpoint
- Max output tokens: 8192 minimum (heavy thinking token usage)

### ADW Pipeline
- Location: `~/apps/agent-issue-hook/`
- Managed via Claude Code skills: `/adw-onboard`, `/adw-submit`
- Purpose: Issue intake, agent dispatch, implementation
- DO NOT RECREATE (mature, running system)

### CSA Pipeline
- Location: `~/Documents/CSA/`
- Managed via Claude Code skills: `/csa-pipeline`, `/csa-feedback-flywheel`, `/project-spec-authoring`, `/spec-to-visual-artifact`
- Purpose: Briefing + input form generation, FTP deploy
- Dashboard: `~/Documents/CSA/index.html` (append-only ledger, 28+ rows)
- DO NOT RECREATE (mature, running system)
- CRITICAL: Dashboard is additive only - use Edit for targeted row insertion, never Write to overwrite

### GitReport
- Downstream system, reads from repos via SSHFS + gh CLI
- DO NOT RECREATE (mature, running system)
- Purpose: Operational source of truth, project status, issue histories, value-delivered metrics

## 9. Brain Integration

NotebookLM serves as persistent memory. The session protocol implements a pull-execute-push cycle.

**Query bridge** (since NotebookLM lacks chat API):
1. Load source content from local `handoffs/` mirror
2. Construct grounding prompt with all source content + question
3. Send to Gemini 2.5 Flash via `generateContent` endpoint
4. Return source-grounded answer

**Brain query example**:
```bash
ops/brain/brain-query.sh "What are the acceptance criteria for the token pipeline?"
# Output: Answer grounded in NotebookLM sources
```

**Brain push example**:
```bash
ops/brain/brain-push.sh "Decision Log - 2026-04-06 - Token Pipeline" < decision.md
# Uploads new source to NotebookLM via batchCreate API
```

**Brain status example**:
```bash
ops/brain/brain-status.sh
# Lists notebooks and sources with metadata (title, wordCount, status, timestamp)
```

**Source inventory** (24 sources, all STATUS_COMPLETE):
- Agentic Frontend CMS Spec - Full architecture, handoff model, system roles, component contracts
- Research - Development Pipeline - Pipeline assessment, system operating model
- Research - Penpot Assessment - Penpot integration patterns, design-to-code workflow
- Research - Agentic CMS Architecture - Tool evaluation, stack recommendations
- (20 additional decision logs, milestone reports, operational lessons)

**Context offloading rules**:
- When a decision is made during implementation, write it back to NotebookLM as a source
- When receiving feedback or review comments, capture and upload to NotebookLM before acting
- When encountering architectural questions, check NotebookLM sources first
- When a session produces new understanding about the system, push a summary source to NotebookLM
- Claude Code's `memory/` files are a lightweight cache; NotebookLM is the canonical store

**API capabilities**:
- Supported: Create/get/delete notebooks, batch add/delete/upload sources, audio overview generation
- NOT yet supported: Chat/query endpoint (no way to ask NotebookLM questions via API)
- Bridge pattern confirmed working: read local mirrors, Gemini API as grounding context

**Auth model**:
- OAuth token: `gcloud auth print-access-token` (for NotebookLM API)
- API key in `.env`: For Generative Language API (Gemini) only
- Two separate auth mechanisms, not interchangeable

## 10. Handoff Model

The delivery lifecycle is GitHub-native, with ADW as the agentic production line and CSA as the communication output layer.

```mermaid
flowchart LR
    I[GitHub Issue/Spec Intake] --> A[ADW Queue]
    A --> B[Research + Planning Context]
    B --> C{Design Needed?}
    C -->|Yes| D[Stitch Ideation]
    D --> E[Penpot Approval + Normalization]
    C -->|No| E
    E --> F[Claude Code Multi-Agent Implementation]
    F --> G[GitHub Pull Request]
    G --> H{Review Outcome}
    H -->|Request Changes| F
    H -->|Approve| J[Merge/Delivery]
    J --> K[EmDash Content/Theme Ops if Applicable]
    J --> L[GitReport Operational Update]
    J --> M[CSA Communication Artifacts]
```

**Handoff stages**:
1. Intake to GitHub and ADW - All implementable work begins as GitHub Issue
2. Research to planning - NotebookLM provides source-grounded research packets
3. Planning to design ideation - Stitch generates visual exploration when needed
4. Design approval to Penpot - Approved concepts normalized in Penpot with semantic naming, token alignment
5. Penpot to implementation via ADW - Claude Code consumes Penpot exports, inspect output, annotations, token definitions
6. Implementation to pull request - All meaningful code output via GitHub PR tied to originating issue
7. Pull request review to refinement - ADW/Claude Code re-invoked for refinement tasks linked to PR review feedback
8. Implementation to CMS/content - EmDash receives schema definitions, block/component mappings, editorial templates
9. Delivery to GitReport and CSA - GitReport receives operational record, CSA generates interactive artifacts

**Quality gates** (before release):
- GitHub issue linkage and PR traceability
- Design parity against approved Penpot artifact
- Accessibility checks across states and breakpoints
- Performance checks for CMS and app surfaces
- Content/schema validation for EmDash-backed pages
- Operational update recorded in GitReport
- CSA source bundle completeness for communication-worthy deliverables

## 11. Git Conventions

**Branch naming**:
```
<type>/<issue-number>-<short-description>

Types:
  feat/     - new feature or enhancement
  fix/      - bug fix
  chore/    - maintenance, infra, tooling
  design/   - design system, token, or Penpot work
  docs/     - documentation only
  artifact/ - CSA artifact generation
```

**Commit messages**:
```
<type>(<scope>): <description>

Types: feat, fix, chore, docs, refactor, test, style, ci
Scopes: brain, tokens, ui, cms, csa, adw, infra
```

**Label taxonomy**:
- Routing: `routing:frontend`, `routing:design`, `routing:cms`, `routing:infra`, `routing:artifact`, `routing:mixed`
- Type: `intake`, `bug`, `task`, `triage`
- Priority: `P0` (critical), `P1` (high), `P2` (medium), `P3` (low)
- Stage: `stage:research`, `stage:design`, `stage:implementation`, `stage:review`, `stage:delivery`
- Status: `blocked`, `in-progress`, `needs-spec`, `needs-design`

**Branch protection** (defined but not yet enforced):
- All work via topic branches + PRs
- PRs must reference originating issue
- Required status checks before merge (when CI exists)

## 12. Environments

**VPS** (app.chem.dev):
- Long-running tasks, ADW queue workers, remote Claude Code sessions
- Production deployment via PM2
- gcloud SDK: `/home/jgatlit/google-cloud-sdk/bin/gcloud`

**XT12** (local):
- Interactive dev, visual QA, design-to-code work
- SSH tunnel for remote access: `ssh -L 3500:localhost:3500 -L 3501:localhost:3501 jgatlit@app.chem.dev`

**Port allocation**:
- 3500 - Next.js (cms-web)
- 3501 - Astro (cms-content)
- Port 3000 unavailable (Flowise)
- Port 3030 unavailable (Flowise)

## 13. Security and Governance

**Secrets management**:
- `.env` files for API keys (never committed)
- gcloud OAuth for NotebookLM API
- Penpot access token in `~/.claude.json` (user-scoped)
- EmDash database not exposed to internet (localhost only)

**Write governance**:
- Read-only integrations by default
- Production writes require explicit approval state
- Research and design proposals cannot directly publish code or content
- Verification failures block promotion to release
- All destructive operations are logged and attributable
- CSA artifacts must derive from approved and traceable delivery records

**HITL escalation**:
- ONLY route to user for changes that are obviously destructive, wasteful, or regressive
- Everything else is brain-guided autonomous execution
- Milestone decisions query brain first, then proceed autonomously

## 14. Lessons Learned

**Operational lessons**:
- ALWAYS DEPLOY AFTER MILESTONES: After committing code that affects production surfaces, MUST rebuild and restart PM2. Stale chunks cause ChunkLoadError 400s. This is part of milestone completion loop, not optional.
- ALWAYS SCREENSHOT DURING FRONTEND TESTING: Any frontend testing, visual QA, or agentic browser viewing MUST capture screenshots and save to server (`static-site/screenshots/` or `handoffs/screenshots/`). Screenshots are evidence - without them, visual validation is unverifiable.

**Technical lessons**:
- Auth model: API key in `.env` is for Generative Language API (Gemini). NotebookLM uses OAuth via `gcloud auth print-access-token`. These are separate auth mechanisms.
- gcloud auth: `gcloud auth login` requires interactive terminal. Cannot pipe verification codes via non-interactive shells.
- NotebookLM PATCH: API does NOT support PATCH/rename on notebooks. Workaround: create new + delete old.
- NotebookLM DELETE: DELETE endpoint returns 404. Deletion must be done via web UI at notebooklm.google.com.
- NotebookLM query API: Does NOT exist yet. Query bridge confirmed working: read local mirrors, Gemini 2.5 Flash as grounding context.
- Gemini model availability: `gemini-2.0-flash` deprecated for new users (404). Use `gemini-2.5-flash` or `gemini-2.5-pro`.
- Gemini 2.5 Flash thinking tokens: Model uses heavy thinking (1000+ tokens per query). Set `maxOutputTokens: 8192` minimum for brain queries.
- EmDash seed.json format: Version must be "1", collections is ARRAY (not object).
- EmDash + Astro 6: Requires Node >= 22.12.0. Use fnm: `fnm use 22`
- EmDash sqlite adapter: Takes `{ url: "file:./data.db" }` NOT `{ filename: "..." }`.
- MCP config location: MCP servers go in `~/.claude.json` (user-scoped) or `.mcp.json` (project-scoped). NOT in `.claude/settings.local.json`.
- CSA Dashboard ADDITIVE ONLY: `~/Documents/CSA/index.html` is an append-only ledger. NEVER use Write to overwrite - ALWAYS use Edit for targeted row insertion.

## 15. Current State

**Project phase**: Production deployment complete

**Delivered milestones**:
- Foundation COMPLETE (12 items)
- End-to-end pilots COMPLETE (2 pilots)
- Feature demo COMPLETE (polished landing, design system catalog, nav shell)
- Kaleido-Life COMPLETE (129 DTCG tokens extracted, showcase surface built)
- E2E Test Plan COMPLETE (ALL 5 TESTS PASSED)
- Production Deploy COMPLETE (PM2 + Caddy + DNS + SSL all live)
- ICP E2E Test Projects COMPLETE (4 ICP projects, 50 new tokens, 4 components, 4 routes)
- Stitch+Penpot Integration COMPLETE (All MCP tools exercised, screens generated)

**Current metrics**:
- 9 shared UI components
- 171 DTCG tokens
- 9 Next.js routes
- 2 Astro pages (pilot content)
- 24 NotebookLM sources (all STATUS_COMPLETE)
- Visual QA: 93/100 (all routes 200, WCAG 2.1 AA)
- CI pipeline: 3 jobs (build-web, build-cms-theme, smoke-tests)
- 12 Playwright smoke tests

**Verified live URLs** (2026-04-06):
- https://cms.chem.dev/ - 200
- https://cms.chem.dev/dashboard - 200
- https://cms.chem.dev/design-system - 200
- https://cms.chem.dev/kaleido-life - 200
- https://cms.chem.dev/pricing - 200
- https://cms-content.chem.dev/ - 302 (EmDash setup redirect)
- https://cms.chem.dev/ref/tokens/ - 200
- https://penpot.chem.dev - 200 (no regression)

**Gaps** (prioritized for next sessions):
1. EmDash content setup - cms-content.chem.dev returns 302 (EmDash first-run setup not completed)
2. Design drift monitoring (Phase 6) - No comparison of implementation vs Penpot artifacts
3. Storybook/component catalog (Phase 4) - `/design-system` route exists but no interactive Storybook
4. Branch protection (Phase 1) - Rules defined but not enforced on GitHub
5. Supervisor/LangGraph (Phase 1) - Spec calls for orchestration layer; brain + skills serve this role informally
6. GitReport automation (Phase 6) - GitReport reads repos but no automated status ingestion hooks
7. CSA source bundle schema (Phase 5) - CSA works but lacks formalized source bundle contract
8. FTP deploy - `ftp.chem.dev` DNS record needed before static mirror can be pushed
9. Component metadata - Spec requires 16 metadata fields per component; current components have metadata in component-meta.ts but not all fields fully populated
10. docs/architecture/ - This README now exists, but no other architecture docs written
11. docs/decision-records/ - Placeholder README only, no ADRs captured
12. packages/schemas/ - Placeholder README only, no shared schemas
13. Dead CTAs - Landing page "Launch Platform" button non-functional

## 16. References

**Key documents**:
- `/home/jgatlit/apps/CMS/CLAUDE.md` - Repository instructions and session protocol
- `/home/jgatlit/apps/CMS/handoffs/agentic_frontend_cms_spec.md` - Full architecture specification
- `/home/jgatlit/apps/CMS/ecosystem.config.cjs` - PM2 configuration
- `/home/jgatlit/apps/CMS/packages/tokens/build.py` - Token transformation pipeline
- `/home/jgatlit/apps/CMS/packages/ui/src/component-meta.ts` - Component metadata registry
- `/home/jgatlit/apps/CMS/.github/workflows/ci.yml` - CI/CD pipeline

**External systems**:
- NotebookLM: https://notebooklm.google.com
- Penpot: https://penpot.chem.dev
- Stitch: https://stitch.withgoogle.com
- EmDash: https://emdash.ai
- GitHub: https://github.com/jgatlit/CMS-aiChemist (private)

**Documentation paths**:
- Repository docs: `/home/jgatlit/apps/CMS/docs/`
- Handoff docs: `/home/jgatlit/apps/CMS/handoffs/`
- Static site: `https://cms.chem.dev/ref/`
- CSA artifacts: `https://io.noboxai.com/pricing-table/` (pilot)