# Product

<!-- impeccable:product-schema 1 -->

> **How this file was written.** Impeccable's `init` normally interviews the
> user before writing anything here. This file was written overnight, on
> Paul's explicit instruction to proceed unattended, so every fact below was
> derived from repository evidence rather than confirmed in an interview:
> `AGENTS.md`, `docs/superpowers/specs/2026-08-30-docs-design.md` (revision 2),
> the four plans in `docs/superpowers/plans/`, and the shipped code in
> `internal/docs/`. Facts traceable to a spec ruling or to code are cited.
> Anything that is a reading rather than a citation is marked
> **[inferred — confirm]** and should be corrected rather than trusted.

## Platform

web

## Users

**Primary: a member of one team, writing and reading that team's documents.**
The instance boundary *is* the team (spec §1, decision 1) — one deployed
instance per team, not one multi-tenant app with teams inside it. Sharing a
document is therefore membership rather than a link-permission matrix.

**Secondary: an outside guest**, admitted as a guest member rather than as an
anonymous URL holder (spec §1, decision 1; §8.2). A guest is a real row with a
real identity, which is what lets author colours key off it (§10.2).

Access today is a magic link, gated by `$DOCS_ALLOWED_ADDRESSES`
(`internal/docs/auth.go`) — a per-instance allowlist. **Instance-local**
passkeys are ruled out on purpose, not deferred: `passkey.Config.Origin`
derives its relying party from the instance's own host, so a person in several
teams would enrol several credentials for one product (spec §8.1). That is a
ruling about *this* app enrolling them, not about passkeys as such — §8.1.1's
suite path deliberately keeps them, at the home's single relying party.

**[inferred — confirm]** The team is assumed to be small enough that an
allowlist of addresses is an appropriate admission mechanism. Nothing in the
repo states a target team size.

## Product Purpose

CARLOS Docs is a **WYSIWYG, paginated, collaborative document editor** with
DOCX, PDF and Markdown in and out (spec preamble). It is one of three moving
parts in the `oficina` suite, alongside CARLOS Sheets (`../sheets`) and a
shared suite home; Docs is a declared consumer of the home contract (§9) and
of rastrillo's colour engine (§10.2).

Success is a document that is genuinely *the same document* everywhere it is
seen: same pagination, same layout, same colour, whether it is being edited in
a browser, replayed server-side into HTML for a reader with no JavaScript, or
exported to PDF.

## Positioning

Three things a neighbouring editor could not truthfully copy without rebuilding
its foundations:

1. **One wire format, two implementations, fixtures as the contract.** The
   browser runs JS `yjs`; the server runs Rust `y-crdt` under wazero. They
   agree because checked-in fixtures generated by the JS side must be
   reproduced by the Rust side (spec §0). This is what makes the server able
   to render, export and thumbnail a document without a headless browser.
2. **The engine owns page geometry; the browser owns line breaking inside
   it** (spec §0, decision 5). Page breaks are ProseMirror decorations, never
   nodes (decision 14), so page geometry never enters the CRDT and two
   collaborators on different page setups never conflict.
3. **Sealed at rest, with a stated leak list — designed and ruled, not yet
   shipped.** The spec's §2 commits to content encrypted in SQLite under a DEK
   held by the running instance, enforced by a test that greps raw SQLite bytes
   and bucket objects for fixture plaintext, and it enumerates the six things
   that *do* leak (§2.1) rather than eliding them.
   Do not describe this instance as encrypting content at rest, and
   do not let this entry be read as a shipped property; it is the position the
   product is being built toward, and the thing that makes the position
   defensible is the leak list, which is honest about what the trade costs.

## Operating Context

- **One Go binary per instance**, `CGO_ENABLED=0`, cross-compiled to
  `linux/arm64`, on the CARLOS platform (spec §3). SQLite, Litestream-replicated.
- **Routes shipped today** (`internal/docs/app.go`): `GET /` (document list),
  `POST /documents` (create), `GET /d/{sqid}` (read/edit), `GET|POST
  /d/{sqid}/updates` (the CRDT update log), plus the sign-in set (`GET|POST
  /signin`, `GET /auth/callback`, `GET /auth/verify`, `POST /signout`) and
  `/static/*`. Every document route sits behind `RequireSession`.
- **Local development** is `./scripts/run-dev.sh` — `localhost:8099`, a scratch
  SQLite database that starts empty every run, magic links logged to the
  terminal rather than mailed.
- **The scriptless path is a product requirement, not a fallback** (spec §6.2):
  reading a document, the list, search, sharing, settings, and reading/replying
  to/resolving comments all work without JavaScript. Editing prose does not,
  and that boundary is stated rather than discovered.
- **Work happens on a worktree branch and reaches `main` only by squash merge**,
  after a highest-capability-model review, Paul's approval, and green CI
  (`AGENTS.md`, Paul's rule 2026-08-30). The review record is an amadan branch
  discussion, not a GitHub PR — this repo is hosted on an amadan hub.

## Capabilities and Constraints

**Shipped:** real per-person sign-in with an admission allowlist; the document
list grouped by recency; document creation; server-rendered read view replayed
from the CRDT through wazero; a ProseMirror editor mounted over that same
container; a save queue with retry, a resync controller, and a save-status
indicator.

**Deliberately not built yet** (spec §14): suggestion mode, footnotes with
tracked-changes import, the version-history timeline, a pageless mode,
full-text search (title and metadata search only — decision 15).

**Binding technical constraints:**

- **Markup uses the bare `rst-*` attribute grammar** (`<div rst-inspector>`),
  variants matched with `~=`. Unparked by Paul 2026-08-31 once `v0.21.0`
  shipped both spellings. Two rules travel with it: **adopt per screen, not per
  element**, and **pin `v0.21.0` or later**. Held by
  `render_test.go`'s `TestOurTemplatesUseTheAttributeGrammar`. Currently on
  `rastrillo v0.22.0`, where the framework itself writes the same spelling.
- **Anything Docs contributes to estilo takes an `estilo-*` prefix, never
  `rst-*`** — that namespace is the framework's and a future version may claim
  a name we took (spec §10.4).
- **`ui` is rastrillo's vocabulary, not ours.** This app's own selectors are
  spelled `[docs-*]` (`[docs-thumb]`, `[docs-canvas]`, `[docs-page]`,
  `[docs-text]`, `[docs-save-status]`).
- **Every user-visible string is a catalog key**, resolved through
  `rastrillo.T` at render time (`internal/docs/render.go`'s `Catalog`). Twelve
  base locales are the target; one (`en`) is declared today. A hardcoded
  English string is a bug. Document titles and timestamps are *data*, not
  authored copy, and are correctly not keys.
- **Tokens are vendored through `ui.TokensCSS()` / `ui.ThemeCSS(name)`**, never
  copied by hand. `rastrillo doctor` mechanises the re-copy step as of `v0.21.0`.
- **A spec ruling, code on `main`, and code in the latest release are three
  different things.** Cite `origin/main` after a fetch, or a tag, and say which.

## Brand Commitments

- **Name:** CARLOS Docs, in the `oficina` namespace at
  `amadan.net/oficina/docs`, hosted per instance at
  `<app>.<sqid>.oncarlos.com` (spec §9.2).
- **The design system is rastrillo's**, themed `day` with the `column` shell
  (`internal/docs/render.go`). The suite variant is **estilo**
  (`amadan.net/oficina/estilo`), named by Paul. Docs owns three primitives —
  **inspector panel**, **presence stack**, **comment thread**; Sheets owns
  toolbar groups (§10.4).
- **The canvas is not themed chrome.** A document is a piece of paper and does
  not follow the reader's dark-mode preference; the canvas opts out with
  `color-scheme: light` and literal colours, never theme tokens (§10.2, spec
  decision 9: canvas light by default, dark is a per-person preference, export
  always renders true colours).
- **Chrome is a short toolbar plus an inspector on demand** (decision 10) —
  explicitly rejecting the dense undifferentiated toolbar, the always-on
  inspector, and the floating-only model.
- **The document list is a list with real rendered page-one thumbnails**
  (decision 11). Explicitly cut: the template carousel, "Owned by anyone" and
  "Last opened by me" filters, grid/list/AZ/folder toggles, and all commercial
  and platform chrome.
- **Voice, as evidenced by the shipped catalog:** plain, unhedged, second
  person, no exclamation marks, no product cheer. "No documents yet"
  (`docs.list.empty.title`, no full stop — a heading, not a sentence).
  "Documents you create will show up here, newest first." Error copy states
  what happened in the past tense and what helps, and was corrected once
  precisely because it described a recovery the person could no longer perform.

## Evidence on Hand

- **Specs:** `docs/superpowers/specs/2026-08-30-docs-design.md` (revision 2,
  1000+ lines, itself the product of a Fable review that returned seventeen
  defects against revision 1).
- **Plans:** four, in `docs/superpowers/plans/` — the Rust core and wire
  compatibility, the app's first screens, sign-in and samples, editing.
- **Sibling specs:** Sheets at
  `docs/superpowers/specs/2026-08-30-sheets-design.md`; the design system at
  `2026-08-28-design-system-design.md` in the rastrillo repo.
- **Published guidance:** https://rastrillo.org/docs/design-system (2026-08-31).
- **Seed content:** `internal/docs/seeddata/` and `fixtures/generate-seed.mjs`
  produce sample documents for a newly created person's space.
- **What does not exist and must not be invented:** no customers, no
  testimonials, no benchmarks, no pricing, no usage numbers, no launch date,
  no press. `[docs-thumb]` is reserved space, not a rendered thumbnail — the
  real page-one rendering arrives with a later plan's layout engine.

## Product Principles

1. **State the degradation rather than let it be discovered.** Where something
   does not work — scriptless comment creation anchoring to a block, layout
   divergence at the line level, the six-item leak list — the product says so
   in the place a reader will look, and the spec refuses to claim zero.
2. **A verification that cannot distinguish "no" from "I can't see it" is not
   a verification.** It is why `git branch --merged` is banned here, why the
   editor bundle is checked by rebuilding it rather than by trusting it, and
   why the seal, when it lands, is specified as a byte-grep over raw storage
   rather than as a code review. The principle is live; the seal is not built
   yet (see Positioning 3).
3. **The empty state is a designed screen, not a blank page** (Paul's ruling,
   in the catalog's own comments).
4. **Chrome is quiet so the document is loud.** Everything around the page is
   design system; the canvas is the one place that diverges, and it diverges
   because paper has different requirements from an admin screen.
5. **A string a person can read is a catalog key.** Localisation is a
   structural property of the app, not a phase.

## Accessibility & Inclusion

**WCAG 2.2 AA, no exemptions** (spec §10.3, restated in `AGENTS.md`). Three
requirements are called out by name because they bind concrete decisions:

- **24×24 minimum target size.**
- **320px reflow** — the page must work at that width without a horizontal
  scroll of the page itself.
- **Colour never carries meaning alone**, which binds the presence stack and
  author colours directly: past the colour engine's separation capacity, the
  name carries identity (§10.2).

Twelve base locales are the target set. Today exactly one exists: `Locales =
[]string{"en"}` (`internal/docs/render.go`). The spec's plan for the other
eleven — machine-drafted catalogs, with each shared primitive shipping prose
keys (§10.4) — is a commitment, not a shipped state, and future work should
not read this section as though those catalogs are sitting in the repo.