Rich Docs

1. Context

Sponic’s primary document workflow is: have a conversation in Claude Code, then ask it to publish a doc to the intranet at in.sponicgardens.com/indocs/. For devtasks specifically this goes through the /devtask skill (which writes four files). For everything else — pitches, recruiting briefs, partner research, runbooks, one-pagers, legal/corp memos, AI host setup — there is no skill. The PM just prompts Claude in conversation: “write me a one-pager at indocs/onepager/foo.html,” and Claude pattern-matches the visual style from a neighboring file and writes the HTML.

The intranet’s indocs/ tree currently holds ~102 HTML files spread across ~20 categories. Roughly 30 are devtasks; the rest are ad-hoc Claude output.

Three pain points have become dominant:

1. The feedback loop is too long. The only way to see the rendered doc is to commit and deploy. Small tweaks become 3–5 minute roundtrips.
2. Every page looks the same. A slide-deck-style document, a diagram-heavy explainer, and a long dense RFC look identical.
3. The docs corpus is hard to navigate. Each category has its own static index.html page. There’s no unified browser, no global search, no cross-category view, no Drive-style “what did I touch recently / what’s shared with me” entry point. Finding a doc means knowing which category it lives in.

Goal

Four things, all load-bearing:

1. Multi-format artifacts behind a single discoverable index — memos as HTML, slide decks as reveal.js, diagrams as SVG, data as sortable tables, freeform sketches as Excalidraw.
2. Lite in-browser editing for memo/markdown so small revisions don’t require a Claude Code roundtrip.
3. Light-touch multi-format INSIDE a doc. A prose memo can embed a chart, diagram, table, or slide-card inline.
4. A Google-Drive-inspired docs browser as the unified entry point. Sidebar nav with Pinned / Recent / Shared / category tree; main pane with grid or list view, global search, sort, filter; right-click context menus; star/pin. Replaces the per-category static index pages.

2. Architecture overview

Five layers, designed independently so they can be built independently:

1. The spine — unified docs registry. A single Supabase table for every artifact regardless of format.
2. The browser — Drive-inspired docs UI. A single /indocs route that queries the registry and renders the Drive-style browser. Replaces all per-category index.html pages.
3. Per-format renderers. Each artifact type has its own renderer; also invokable as inline blocks inside a memo via markdown directives.
4. The Lite Editor. An authenticated in-browser editor for markdown-backed formats. Saves via GitHub Contents API.
5. Access control. Per-category defaults + per-doc ACL overrides. Admins always have edit access; admins delegate Google-Docs-style.

3. The registry — public.indocs

3.1 Schema sketch

CREATE TABLE public.indocs (
  slug TEXT PRIMARY KEY,
  type TEXT NOT NULL,                  -- memo | deck | diagram | table | freeform | custom
  category TEXT NOT NULL,              -- devtasks | pitch | recruiting | corp | botanics | …
  title TEXT NOT NULL,
  subtitle TEXT,
  description TEXT,
  tags TEXT[] DEFAULT '{}',
  status TEXT,
  view_url TEXT NOT NULL,
  edit_url TEXT,
  download_url TEXT,
  source_path TEXT,
  owner TEXT,
  acl JSONB DEFAULT '{}',              -- { "editors": ["[email protected]"], "viewers": "intranet" }
  pinned BOOLEAN DEFAULT false,
  starred_by TEXT[] DEFAULT '{}',      -- emails who have starred (Drive-style)
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now(),
  last_edited_by TEXT,
  live_status JSONB
);

3.2 Who writes to the registry

• /docs skill writes a row on doc creation.
• Lite Editor updates updated_at + last_edited_by on save.
• Drive-style browser updates starred_by when a user stars a doc.
• Migration script (Phase 1) backfills every existing doc.

4. The generalized /docs skill

/devtask becomes a thin alias for /docs --category devtask --type memo. Invocation shapes:

/docs                                    → interactive: asks for category + type
/docs --category recruiting              → memo in recruiting/ (type defaults to memo)
/docs --category devtask --type memo     → equivalent to today's /devtask
/docs --category pitch --type deck       → reveal.js deck under pitch/
/docs --category corp --type diagram     → mermaid/D2 diagram under corp/
/docs --category botanics --type table   → sortable xlsx/csv under botanics/

Skill derives slug, picks source path per type, writes source file with frontmatter, inserts registry row with category-default ACL + owner, returns view_url. The four-files pattern of today’s /devtask collapses to two files (source + registry row).

5. Markdown source + request-time rendering

5.1 Decision: request-time rendering

The body of every memo is rendered at request time by a Next.js dynamic route at apps/control/src/app/(public)/indocs/[category]/[slug]/page.tsx. Cloudflare Pages serves the route via OpenNext (already in package.json as @opennextjs/cloudflare).

5.2 The markdown directive layer

Standard markdown + custom directives: :::callout-green / :::callout-gold / :::callout-warn, :::flow, :::toc, :::mermaid / :::d2, :::chart, :::deck-slide, :::table-from src="...". Implementation: remark-directive + custom plugin.

6. The Lite Editor

• Visit a type: memo doc signed in → Edit button (if ACL-permitted).
• Click → TipTap/Lexical editor loads from markdown.
• Save → Next.js route handler commits via GitHub Contents API.
• Request-time render picks up the new markdown on next load — sub-second.

Commits attribute to sponic-lite-editor[bot] with editor’s name in body. Conflict handling: stale SHA → refresh. Editable in v1: prose, headings, lists, callouts, inline tables, code blocks. Not editable: frontmatter, Build Journal, images.

7. Access control

There is no existing in-browser editor in apps/control. But apps/control/public/indocs/auth-guard.js already supports per-page allowlists and role gates (admin/staff/resident). The Lite Editor reuses this auth client.

7.1 Permission model

// apps/control/src/lib/indoc-acl.ts
export const CATEGORY_DEFAULTS = {
  devtasks:   { edit: "signed-in", view: "intranet" },
  recruiting: { edit: "admin+staff", view: "intranet" },
  pitch:      { edit: "admin",      view: "admin+staff" },
  corp:       { edit: "admin",      view: "admin+staff" },
  legalcorp:  { edit: "admin",      view: "admin" },
};

Per-doc acl JSONB overrides:

{
  "editors": ["[email protected]", "[email protected]"],
  "viewers": "intranet"
}

Per-doc ACL wins if set. Admins always have edit access regardless. Read-side: auth-guard.js. Edit-side: save endpoint checks user email server-side.

8. Format catalog

8.1 Memo (default)

Markdown source → directive layer + page shell, request-time. Edited via Lite Editor.

8.2 Slide deck

Per-slide markdown (--- separator) → reveal.js + Sponic theme. Optional .pptx via pptxgenjs. Edited via Lite Editor.

8.3 Diagram (text-based)

Mermaid or D2 source → SVG. Edited via Lite Editor source-view.

8.4 Data table

xlsx/csv → sortable HTML table + download. Upload-only.

8.5 Freeform diagram (stretch)

Excalidraw JSON → embedded Excalidraw viewer + Edit toggle. Saves via GitHub Contents API.

8.6 Custom (existing hand-designed pages)

Hand-designed HTML (branding.html, ipitch.html, etc.) stays as-is; indexed but editor not exposed.

8.7 Embedded artifacts within memos

A memo can embed any renderer as an inline block:

## System architecture

:::mermaid
graph TD
  Registry --> MemoRenderer
:::

The numbers for Q3 are:

:::table-from src="../data/q3-numbers.csv"

Same renderer powers standalone artifact + embed. Lite Editor treats unfamiliar directives as opaque "edit source" widgets; familiar ones get inline visual editing.

9. User journeys

Journey A — Create a memo from CC

1. PM has a conversation in CC.
2. PM invokes /docs --category devtask.
3. Skill writes docs/devtasks/<slug>.md and inserts registry row.
4. Auto-push commits and pushes.
5. PM opens https://in.sponicgardens.com/indocs/devtasks/<slug> — live via request-time renderer.

Journey B — Tweak an existing memo in browser

1. PM opens a doc; sees Edit button (ACL-permitted or admin).
2. Click → in-place editor loads from markdown.
3. PM fixes a typo.
4. Click Save → endpoint commits via GitHub Contents API.
5. Page reloads → change visible in <1s. No CC session opened.

Journey C — Substantively rework an existing memo

1. PM opens a new CC session.
2. Claude edits markdown at docs/<category>/<slug>.md.
3. Auto-push picks it up; live in seconds.

Journey D — Create a deck/diagram/table from CC

1. PM invokes /docs --category pitch --type deck (or --type diagram, --type table).
2. Skill writes source file + registry row.
3. PM opens rendered URL.

Journey E — Find a doc (Drive-style browser)

1. PM opens https://in.sponicgardens.com/indocs/ — the Drive-inspired browser.
2. Sees: sidebar with Pinned / Recent / Shared with me / My docs / category tree with counts. Main pane in grid view.
3. Two paths to a doc: (a) browse via sidebar category click → grid filters → click card; or (b) global search bar → results across all categories → click result.
4. Each card shows: type icon, title, description, modified date, owner avatar, share-status icon, star toggle.
5. Toolbar: switch to list view for sortable columns; sort dropdown; filter by type/tag/owner.
6. Right-click card → context menu (Open, Open in new tab, Edit, Share, Star, Copy link, Move to category).
7. Star a doc → appears under Pinned sidebar item.

Journey F — Share/restrict edit access

1. Admin opens a doc, clicks Share in the doc header.
2. Modal opens: current effective editors listed.
3. Admin adds a colleague’s email; "Save permissions" updates registry acl JSONB.
4. Colleague sees Edit button and the doc appears under their Shared with me sidebar item.

10. Docs browser UX (Google-Drive-inspired)

The unified browser at /indocs is the single entry point for finding any doc in the corpus. Inspired by Google Drive’s navigation paradigm, adapted to the Sponic visual language.

10.1 Layout

Two-pane (sidebar + main), responsive (sidebar collapses to hamburger on mobile):

10.2 Sidebar — Quick Access

• ★ Pinned — docs the user has starred (starred_by contains their email).
• 🕐 Recent — docs sorted by updated_at desc, limited to docs they have view access to.
• 👥 Shared with me — docs where the user’s email is explicitly in acl.editors.
• 📝 My docs — docs where owner matches the user’s email.

10.3 Sidebar — Categories

Collapsible tree. Each node: category name + doc count. Click a category → main pane filters. v1 stays flat with one level.

10.4 Main pane — Grid view (default)

Doc cards with: type icon (memo = page, deck = slides, diagram = node graph, table = grid, freeform = pencil, custom = star), title (2-line truncate), description preview (1-line truncate), owner avatar, modified date, share-status icon (lock = private, people = shared, globe = public), star toggle.

10.5 Main pane — List view

Sortable table: Icon | Title | Type | Category | Modified | Owner | Actions. Column header click toggles sort. Persists to localStorage.

10.6 Toolbar

• View toggle (grid / list) — persists to localStorage.
• Sort dropdown — Modified / Name / Type / Owner / Created.
• Filter dropdown — by type, tag, owner, modified date range.
• + New button — dropdown of types; clicking copies the right /docs --category <current> --type <X> invocation to clipboard with a “paste this into Claude Code” toast.

10.7 Search

Global search bar (top of main pane). Hits PostgreSQL full-text on title + description + tags + category. Results in a dropdown below the search bar (live, debounced 200ms).

10.8 Right-click context menu

Per card / row: Open, Open in new tab, Edit (if permitted), Share (admin always; editors if per-doc ACL exists), Star/Unstar, Copy link, Move to category (admin only).

10.9 Breadcrumb

Top of main pane. Home, Home › Devtasks, Home › Devtasks › Rich Docs. Each segment clickable. Replaces the current ← All docs link on individual doc pages.

10.10 Per-doc page changes

Breadcrumb at top replaces current ← All docs button. Optional collapsible sidebar showing other docs in same category. Type icon next to title.

10.11 What we adopt from Drive, what we don’t

Adopted: sidebar nav with Pinned/Recent/Shared/category tree; grid vs list view toggle; breadcrumb navigation; right-click context menus; star/pin; global search bar; type icons.

Not adopting (out of scope): thumbnail previews (content renders fast enough); multi-select / batch operations; detailed activity timeline; comments / suggestions (no inline collaboration — anti-goal); file versioning UI (git history is truth); trash/restore (deletes go through git revert); real-time presence indicators.

11. Migration plan

The intranet has ~102 HTML files in indocs/. Three tiers, deliberately decoupled.

11.1 Tier 1 — Registry backfill (Phase 1)

A one-shot Node script (apps/control/scripts/backfill-indocs-registry.mjs) walks all indocs/**/*.html files, extracts metadata, cross-references docs-tab.tsx, upserts into public.indocs with type: "custom" as default.

11.2 Tier 2 — Memo conversion (Phase 5)

Per-doc, Claude-assisted batch conversion. For each: read HTML, extract prose, convert to markdown + directives, write docs/<category>/<slug>.md, update registry to type: memo, delete static HTML.

Sequence:

• First batch: 30 devtasks (already have markdown sources).
• Second batch: high-traffic categories (sop/, reference/, aihost/).
• Third batch: lower-traffic categories (recruiting/, corp/, botanics/).

11.3 Tier 3 — Leave as custom

Genuinely hand-designed HTML pages stay as type: custom: branding.html, ipitch.html, onepager.html, pressuretest.html, sohocompare.html, onepageroutline.html, polishbiznotes.html, privacy.html.

12. End state — what success looks like

For the PM creating a new doc

• One skill (/docs) for every category.
• One source file per doc.
• No hand-rendered HTML.

For the PM editing an existing doc

• Click Edit on any memo (with permission). Save. Live in <1s. No CC session.
• For bigger reworks: open a CC session against the markdown source.

For the PM finding a doc

• One Drive-style browser at /indocs/. Sidebar (Pinned / Recent / Shared / categories). Grid or list. Global search. Right-click menus. Star/pin.

For the team’s permissions story

• Sensible category defaults. Per-doc overrides via Share modal. Admins always have full access.

For the multi-format story

• Memos can embed mermaid diagrams, charts, small CSVs, and slide-style cards inline.
• Standalone deck / diagram / table artifacts exist as first-class entries.

13. Build safety principles

These invariants hold across every phase. If a sprint plan violates one, redesign the sprint before starting.

1. Worktree-first. Every phase builds in .claude/worktrees/rich-docs-pN. No work happens on main. The worktree’s dev server is the verification surface. Only when the worktree’s verification checklist passes does the work merge to main via /ship.
2. Feature flags everywhere. Every new surface — registry browser, Drive-style UI, request-time route, Lite Editor button, Share modal, each new artifact type — ships behind a flag in apps/control/src/lib/feature-flags.ts. Default OFF on first merge to main. Flip on manually after monitoring. Rolling back = flipping a flag, not reverting commits.
3. Dual-write / parallel-run during cutover. New systems run alongside old until proven equivalent. /docs writes registry rows alongside files. Request-time route serves alongside static HTML. Drive-style browser renders alongside per-category index pages. Old system only deleted after new one is verified for every doc.
4. Per-doc opt-in for migrations. Docs migrate to the new system one at a time via a frontmatter flag (request_time_render: true). A doc that hasn’t opted in keeps serving its static HTML exactly as before.
5. Reversible until the last step. Most operations reversible (toggle flags, delete registry rows, revert frontmatter). The only irreversible operation is deleting the static HTML file for a migrated doc — and that only happens after its request-time render is verified visual-diff identical against the static HTML for that specific doc.
6. Verification in the worktree before merge. Each sprint has an explicit verification checklist. Visual diffs, behavior tests with multiple user roles, and quantitative checks all part of the checklist. No merge without checklist sign-off.
7. Production gate after merge. After merging to main, the CF Pages deploy fires (~1-3 min). Production gate criteria specify what must be verified on the live URL before flipping the feature flag on.
8. Schema changes are additive only. New columns and tables fine. DROP COLUMN / DROP TABLE only after features using them are confirmed dead AND data backed up.
9. Static HTML is the safety net. Even after migration, the ability to fall back to static HTML serving (via flag flip) remains until Phase 10 ships. The CF Pages static deploy isn’t dismantled — it becomes a fallback path.

14. Implementation phases (agile sprint plan)

Each phase is a sprint built in its own worktree, verified locally, then merged to main behind a feature flag (default off). The flag flips on only after a brief production monitoring window. Use /feature rich-docs to pick up the next un-started phase.

15. Open questions

• Markdown directive syntax confirmation. remark-directive (:::name) vs MDX. Confirm before Phase 4.
• Editor lib choice. TipTap (default) vs Lexical. Decide when Phase 5 starts.
• Registry vs git as source of truth for metadata. Proposed: frontmatter wins; registry is a derived index.
• Deck-to-pptx priority. Live reveal.js URL sufficient, or PMs need downloadable .pptx?
• Cache invalidation depth. Phase 4 ships with simple TTL caching. Commit webhook for edge invalidation is a v1.1 question.
• Tier 2 migration ordering after devtasks. By traffic, by category leader, by ease of conversion?
• Drive-style “shared with me” semantics. Show only docs where user is in acl.editors, or also docs where they’re owner? Probably split into “My docs” and “Shared with me”.
• + New button behavior. Phase 2 copies invocation to clipboard. Direct CC integration possible? Defer to feedback.

Build journal