From fe62df1a14d1711929f5b45a6ff5d0f6d8059ce2 Mon Sep 17 00:00:00 2001
From: Keysat <licensing@keysat.xyz>
Date: Fri, 19 Jun 2026 11:40:07 -0500
Subject: [PATCH] Refresh Current state: mobile design distilled into contract;
 implementation planning next

---
 AGENTS.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index a51d169..639ae2b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -75,7 +75,7 @@ Subsystem rules live in `docs/guides/` and lazy-load in Claude Code via `.claude
 - **Env:** secrets in `.env` (gitignored); names in `.env.example`. Verified names: `ANTHROPIC_API_KEY`, `SPARK_CONTROL_URL`, `SPARK_CONTROL_VERIFY_TLS`, `QDRANT_URL`, `X_API_KEY`, `CRM_DB_PATH`, `CRM_DEV_DB_PATH`. Also used: `CRM_SECRET_KEY` (beta/prod), `CRM_HOST`/`CRM_PORT`, `CRM_DATA_DIR`; digest mailer: `CRM_DIGEST_SENDER` (DWD impersonation sender) + `SMTP_HOST`/`SMTP_PORT`/`SMTP_SECURITY`/`SMTP_FROM`/`SMTP_USERNAME`/`SMTP_PASSWORD` (SMTP fallback); daily digest (Phase B): `CRM_DIGEST_ENABLED` + `CRM_DIGEST_SEND_HOUR` **only seed the first-boot default** — the live control is the DB policy (`app_settings.digest_policy`, set in Settings → Admin).
 - **Config placement:** operational/feature toggles live in the **admin panel**, DB-backed via `app_settings` (read-merge through a `load_*_policy(conn)` helper shared by the API + any scheduler; precedence DB-row → env-seed → default), so they're discoverable and take effect live. Reserve StartOS actions / env for **secrets and deploy-time config** (SMTP creds, API keys, DWD sender). Precedent: `digest_policy` (`GET/PATCH /api/admin/digest/policy`), `fundraising_backup_policy`.
 - **Agent/bot API access — three roles now (`admin`/`member`/`bot`).** `require_admin` is the only hard gate; everything else is "authenticated" (member, admin, *and* bot all pass). The **`bot` role** (added v0.1.0:89) is authenticated-but-never-admin: `require_bot_or_admin` gates agent-facing endpoints (e.g. `/api/intake/email-proposals*`) so a bot credential reaches *only* what it needs, never user-management/settings/security. Provision it via Settings → Admin edit-user dropdown (kept out of the teammate-invite form). **Two axes to keep separate as more agent capability lands:** the role controls *reach* (which endpoints); the per-feature human draft→approve gate controls *autonomy* (acting unattended). Money/merge/delete mutations stay behind the approval gate regardless of role. Don't build a finer capability/scope system until real NL-mutation endpoints exist to scope against.
-- **Design:** before building or changing any user-facing UI, read `design/DESIGN.md` and `design/tokens.tokens.json` and conform to them. A **mobile-first redesign** is in flight — read `design/BRIEF.md` before any responsive/layout work. (Note: inline `style={{}}` objects can't respond to media queries; responsive layout belongs in the CSS `<style>` block.)
+- **Design:** before building or changing any user-facing UI, read `design/DESIGN.md` and `design/tokens.tokens.json` and conform to them. The **mobile-first redesign landed** (Claude Design round-trip distilled into the contract 2026-06-19): the authority for mobile/responsive work is **`DESIGN.md` §8** + the tokens `mobile` and `color.light` groups; `design/BRIEF.md` is the input brief and `design/_imports/2026-06-19/` the provenance + per-surface interaction reference (the comps are Claude Design runtime prototypes — re-author each surface in the app's React idiom + real API, not drop-in). A **light theme** is adopted as a planned, toggle-gated feature (dark stays default). (Note: inline `style={{}}` objects can't respond to media queries; responsive layout belongs in the CSS `<style>` block — and the inline-style→CSS migration is the unscoped prerequisite gating mobile implementation, see `ROADMAP.md`.)
 - **Commit style:** imperative subject, concise body explaining the *why*; put the package version in the subject (`… (v0.1.0:NN)`) for shippable changes. **No AI co-author / attribution trailers** — commits are authored by the user.
 
 ## Always
@@ -107,13 +107,13 @@ Subsystem rules live in `docs/guides/` and lazy-load in Claude Code via `.claude
 
 ## Current state
 
-_Phase 0 + Phase 1 built; **box + repo live at v0.1.0:94**. **The fundraising grid + email capture is the canonical system of record.** Two active threads: **mobile-first redesign** (design phase, with Grant) and **W2 NL query** (live; web "Ask" box outstanding). History: git log + `start9/0.4/startos/versions/`; backlog/debt: `ROADMAP.md` / `EVALUATION.md`._
+_Phase 0 + Phase 1 built; **box + repo live at v0.1.0:94** (`main` ahead by docs/design-only commits since). **The fundraising grid + email capture is the canonical system of record.** Active threads: **mobile-first redesign** (design DONE → implementation planning next) and **W2 NL query** (live; web "Ask" box outstanding). History: git log + `start9/0.4/startos/versions/`; backlog/debt: `ROADMAP.md` / `EVALUATION.md`._
 
-- **Mobile-first redesign — design phase, in progress with Grant.** Design contract live (`design/DESIGN.md` + `tokens.tokens.json` + `BRIEF.md`). This session: sanity-checked the brief vs the real backend (added a "Backend reality" note to `BRIEF.md` §3a — the grid has **no field-level write** (one versioned JSON-blob PUT; single-investor writes should use the targeted `log-communication` path), and **pipeline stage is a separate 2-call flow**). **Locked the pipeline-stages/flags redesign** (full spec in `ROADMAP.md`): 4-stage funnel **Lead→Engaged→Diligence→Commitment**, auto-derived **Existing-Investor** flag (`total_invested>0`), **Priority+Graveyard** the only disposition flags (Longshot dropped), **staleness** as a last-contact recency overlay (grey→amber→red, one global threshold) + a **W1b** Matrix nudge (never auto-demote). A Claude Design cloud session is iterating screens; `BRIEF.md` §3a card model aligned to these.
-- **Built, deploy pending:** **drag-reorder grid views** (frontend-only; `moveViewBefore` in `index.html`; persists via the existing autosave → `views_json`; render-smoke green, browser-interaction untested). A one-off batch of 8 ideas captured in `ROADMAP.md`; the spark-control dashboard-card item → `standards/INBOX.md`.
-- **W2 — NL query (read-only): LIVE** (v93; matched-only fix v94). Local-Qwen translate → curated parameterized intents + slot validator (trust boundary; no generic SQL), `POST /api/query/nl`, audited; Matrix Q&A room + intake `?`/`@bot` trigger live. Remaining: **in-room human smoke** + **step-4 web "Ask" box**. Guides: `docs/guides/nl-query.md` + matrix-intake.
-- **W1 — reminders: LIVE (v93).** Tickler tied to the grid (migration `0006`, `/api/reminders`, derived `reminder_status`, `last_activity_at` rollup). Deferred **W1b** = nurture-gap auto-suggested reminders (the redesign's staleness nudge specializes it to Engaged/Diligence).
+- **Mobile-first redesign — design phase COMPLETE; implementation not started.** This session ran the `/design` round-trip Phase C/D: distilled the Claude Design cloud output ("Venture-CRM mobile redesign") into the contract — `DESIGN.md` §8 (responsive) + §4 (mobile component states) + §3 (15px scale), tokens `mobile` group + `color.light`, provenance + per-surface interaction reference in `design/_imports/2026-06-19/`. **Light theme adopted as a planned, toggle-gated feature** (dark default). Comps are Claude Design **runtime prototypes** — re-author each surface in React against the real API, not drop-in. Process learnings pushed to `standards/guides/design.md`.
+- **Built, deploy pending:** **drag-reorder grid views** (frontend-only; `moveViewBefore` in `index.html`; persists via autosave → `views_json`; render-smoke green, browser-interaction untested).
+- **W2 — NL query (read-only): LIVE** (v93; matched-only fix v94). Local-Qwen translate → curated intents + slot validator (no generic SQL), `POST /api/query/nl`, audited; Matrix Q&A + intake `?`/`@bot` live. Remaining: **in-room human smoke** + **step-4 web "Ask" box**. Guides: `docs/guides/nl-query.md` + matrix-intake.
+- **W1 — reminders: LIVE (v93).** Grid-tied tickler (migration `0006`, `/api/reminders`, derived `reminder_status`, `last_activity_at` rollup). Deferred **W1b** = nurture-gap auto-suggested reminders (staleness nudge → Engaged/Diligence).
 - **Done & live:** email-proposal Matrix review + `bot` role (v91); grid-driven Pipeline (v88); Matrix intake bot; Gmail capture (DWD) + propose→approve + daily digest; Thesis Workshop + Architect (Claude, dual-approval); outreach drafts. All draft-only.
-- **Tests:** **35/35 backend green** (`python3 backend/run_tests.py`), `py_compile` clean; render-smoke gates `make`.
-- **Next (priority order):** 1) mobile-first implementation once the design session lands — prerequisite is the **inline-style→CSS migration** (responsive can't live in ~1300 inline styles); 2) build the **locked pipeline-stages/flags spec** (one-time enum + data migration + derived flags/overlay); 3) **deploy** the view-reorder (next s9pk build); 4) **W2 step-4** web Ask box + in-room Q&A smoke; 5) **W3** bot grid-mutations behind the Matrix gate; 6) **W1b** nurture-gap reminders; then P2 debt (reports comms-aggregate soft-delete sweep, `?limit=abc` crash, auth regression test, oversized icon).
-- **Open / risks:** mobile responsiveness is **blocked on the inline-style→CSS migration** (large, not yet scoped); W2 translation only **happy-path-validated**; **Claude/Architect path still unverified live on the box**; v2.0 reserve-asset spine approved but **not canonical** (needs dual sign-off); doc drift — `crm-overview.md` + `EVALUATION.md` still call `lp_profiles` live.
+- **Tests:** **35/35 backend green** (`python3 backend/run_tests.py`), `py_compile` clean; render-smoke gates `make`. (Docs/design only this session — no code touched.)
+- **Next (priority order):** 1) **mobile implementation plan** — scope the **inline-style→CSS migration** first (responsive can't live in ~1300 inline styles, still unscoped); 2) land the **locked pipeline-stages/flags** data layer (enum + migration + Existing-Investor derive + staleness); 3) build the 4 mobile surfaces (Grid first; writes via one-row `log-communication` + pipeline link→stage, never whole-grid PUT; light theme co-lands with the CSS migration); 4) **deploy** view-reorder (next s9pk build); 5) **W2 step-4** web Ask box + in-room smoke; 6) **W3** bot grid-mutations behind Matrix gate; 7) **W1b** nurture-gap reminders; then P2 debt (reports comms-aggregate soft-delete sweep, `?limit=abc` crash, auth regression test, oversized icon).
+- **Open / risks:** mobile implementation **blocked on the unscoped inline-style→CSS migration**; W2 translation only **happy-path-validated**; **Claude/Architect path still unverified live on the box**; v2.0 reserve-asset spine approved but **not canonical** (needs dual sign-off); doc drift — `crm-overview.md` + `EVALUATION.md` still call `lp_profiles` live.