amadan
docs: slice 6 plan, deploy docs against main 9225ec2
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CzvnuKhLzudvq7jZ7SvVt2
1 file changed,
+157
−0
docs/superpowers/plans/2026-09-14-meet-slice-6-deploy.md+157 −0
CI passed — run details
diff --git a/docs/superpowers/plans/2026-09-14-meet-slice-6-deploy.md b/docs/superpowers/plans/2026-09-14-meet-slice-6-deploy.md| new file mode 100644 |
| index 0000000..dbbce1a |
| --- /dev/null |
| +++ b/docs/superpowers/plans/2026-09-14-meet-slice-6-deploy.md |
| @@ -0,0 +1,157 @@ |
| +# Meet Slice 6: Deploy Docs Implementation Plan |
| + |
| +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
| + |
| +**Goal:** Close the Meet programme (spec §12 item 6) with the documents a deployed app owes: README, PRODUCT.md, the *Consumed suite rulings* commit for suite Appendix A.6, AGENTS.md's final notes, and the slice record, each true of main as it is on 2026-09-14. |
| + |
| +**Architecture:** Documentation only. Nothing under `internal/`, `native/`, `meetcore/` or `protocol/` changes. Every sentence about behaviour is checked against the code on main `9225ec2` before it is written, and cites the spec section or file it comes from. Items of the programme's slice 6 that other sessions have already delivered or are delivering are recorded as such, not redone. |
| + |
| +**Tech Stack:** Markdown; the spec at `docs/superpowers/specs/2026-09-07-meet-design.md` (revision 9 plus the 2026-09-10 and 2026-09-12 amendments on main); the suite sharing doctrine at `oficina/suite` `docs/superpowers/specs/2026-09-05-suite-sharing-doctrine.md` revision 8, main `1ac4323`. |
| + |
| +**Spec:** `docs/superpowers/specs/2026-09-07-meet-design.md` §7.3, §9, §10, §11, §12 item 6, §0.2. Programme: `docs/superpowers/plans/2026-09-09-meet-slices-2-6-programme.md` (slice 6 line and §5). |
| + |
| +## Global Constraints |
| + |
| +- Branch `slice/6-deploy` from main `9225ec2`; docs only; `make ci` stays green (it is unaffected by Markdown, run it once at the end). |
| +- No user-facing app string changes. Copy review is waived for this round by Paul's steering on `oficina/suite` discussion 5 ("copy review is explicitly waived for this entire massive round"); README and PRODUCT.md prose is catalogued in the record, not reviewed. |
| +- Every claim about behaviour is verified against the code on `9225ec2` (not against memory of earlier slices) and cites its source. A claim that cannot be verified is not written. |
| +- The README's first paragraph carries the scriptless-floor sentence (spec §9: browser media participation needs script, everything else works with scripts off) and the second paragraph is the relay paragraph (spec §5.2, §5.5: ICE servers come from the platform relay through `CARLOS_RELAY`, Meet names no STUN or TURN server of its own; with no relay, calls are direct only). |
| +- Nothing here restates a suite ruling; §0.2 names rulings by number (doctrine Appendix A intro: "delete the restatement, name the ruling"). |
| + |
| +## What slice 6 was, and what it is now |
| + |
| +The programme (2026-09-09) listed for slice 6: PRODUCT.md, the README with the floor and relay paragraphs first, AGENTS.md's final notes, the acknowledgements page, the *Consumed suite rulings* commit for suite Appendix A.6, the Estilo theme pin if a tagged release exists, and the production promotion with its notification. Since slice 5 shipped (a283c53, 2026-09-11) other sessions landed on main: Home sign-in (`7.1.1`, `internal/meet/home.go`), the shared Estilo day theme and brand (`f9cb47f`, `34fc367`; `amadan.net/oficina/estilo.git` as an indirect pseudo-version), the invitation `Share` route (`POST /m/{sqid}/share`, 2026-09-12 amendment), and the native Mac, iPhone and iPad apps (`native/`, `meetcore/`, `protocol/`, tag `v0.1.0` at `9225ec2`). Therefore: |
| + |
| +| Programme item | Disposition in this slice | |
| +|---|---| |
| +| PRODUCT.md | Task 2, here. | |
| +| README with floor and relay paragraphs first | Task 1, here. | |
| +| AGENTS.md final notes | Task 1, here (deploy and gate notes only; the file already carries the native and sharing notes added on main). | |
| +| Acknowledgements page | **Not built here.** `oficina/meet` discussion 10, branch `feat-open-source-credits` (`117b6e4`, `bbc126e`): a shared Estilo credits page with a runtime dependency inventory, Fable-approved, verified live on the overnight canary, not yet merged to main. Slice 6 records it and defers to it; building a second one would be the duplication the programme forbids. | |
| +| Estilo theme pin if a tagged release exists | **No tag exists** (`git ls-remote --tags` on `oficina/estilo` is empty on 2026-09-14). The theme is nevertheless already adopted on main at a pseudo-version by the Home integration. Recorded in §15.18; not changed. | |
| +| Consumed suite rulings commit | Task 3, here: §0.2 refreshed against doctrine main `1ac4323` (still revision 8) and against what main now consumes (Home hand-off, the Share amendment), in one commit titled so Appendix A.6 can point at it. | |
| +| Production promotion with its notification | **No deploy from this slice.** The change is documentation; edge (`meet.oficina.works`) is being promoted by hand by Paul (`651cff2` on 2026-09-12) with other sessions' work queued behind live checks (discussion 14). A docs-only redeploy would drop live calls for nothing. The notification posted on discussion 3 says so in those words; a queued promotion is never announced as live (programme §5). | |
| + |
| +--- |
| + |
| +### Task 1: README.md and AGENTS.md's final notes |
| + |
| +**Files:** |
| +- Create: `README.md` |
| +- Modify: `AGENTS.md` (append a short "Deploying" section after "Serving"; do not touch existing lines) |
| + |
| +**Interfaces:** |
| +- Consumes: spec §3.3/§3.4 (the floor sentence on the holding page and room: find the exact shipped sentence in `internal/meet/templates/join.html` and `room.html`), §5.2/§5.5 (relay), §7.1.1 (Home), §7.3 (deploy), §8 (agents), `native/README.md`, `Makefile` targets, `cmd/meet/main.go` (env vars), `internal/meet/config.go` (which are refused when empty outside development). |
| +- Produces: the README that PRODUCT.md (Task 2) and the record (Task 4) link to. |
| + |
| +- [ ] **Step 1: Verify each fact you will state** by reading the file it comes from on this branch. Keep a list of `claim → file:line` for the report. |
| + |
| +- [ ] **Step 2: Write `README.md`** with this shape (the paragraphs in this order; write them as prose, not as this outline): |
| + |
| +```markdown |
| +# Meet |
| + |
| +<Paragraph 1: what Meet is (video calls for one team: create or schedule a |
| +meeting, share a link, a holding screen, a room of up to four, chat, screen |
| +share, an agent API), and the floor sentence: every screen works with |
| +JavaScript disabled except browser media participation, the camera preview |
| +and join button on the holding screen and the call itself in the room; both |
| +pages render their title, standing, floor notice and navigation without |
| +script (spec §9).> |
| + |
| +<Paragraph 2: the relay. ICE servers come from the CARLOS platform relay, |
| +delivered as CARLOS_RELAY and minted per call at GET /m/{sqid}/ice; Meet |
| +names no STUN or TURN server of its own (suite ruling 6); with no relay |
| +configured, calls are direct only and the holding screen says so. Enabling |
| +or rotating the relay restarts the instance (spec §5.2, §5.5, §15.13).> |
| + |
| +## Sign-in |
| +<magic link to an allowlisted address (MEET_ALLOWED_ADDRESSES); a meeting |
| +link gives an outsider a guest grant at sign-in, never a way in without a |
| +name; optional Home sign-in with the four MEET_HOME_* settings, all or |
| +none (spec §7.1.1).> |
| + |
| +## The room |
| +<P2P mesh of up to four, perfect negotiation, SSE stream + POST signal, |
| +waiting queue for guests, removal and takeover through confirm pages, |
| +chat fanned out and never stored, screen share as a second tile; every |
| +deploy drops live calls because the hub is in-process (spec §4, §5, §6).> |
| + |
| +## Agents |
| +<Settings mints a token shown once; bearer-only /api/v1 (list, create, |
| +replace links, end, get); reach re-derived per request; 60/min per agent; |
| +spec §8 and §15.17.> |
| + |
| +## Native apps |
| +<one paragraph pointing at native/README.md and native/ios/README.md; |
| +make native-mac; same server and shared Go core; no embedded webviews.> |
| + |
| +## Building and gates |
| +<make ci (CGO_ENABLED=0), make race (the cgo exception, tests only), |
| +make browser (real Chromium, 31+ scenarios, about nine minutes, must run |
| +with the Claude Code bash sandbox off: UDP is blocked inside it), make |
| +native-test; make release VERSION=<sha> stamps /api/version.> |
| + |
| +## Deploying |
| +<unit route on CARLOS; carlos deploy --app meet --account oficina with the |
| +build probe on /api/version; secrets MEET_INSTANCE_KEY, MEET_DEK (32 base64 |
| +bytes), mail via MEET_SMTP_* with CARLOS_SMTP_* as fallback; env |
| +MEET_ORIGIN, MEET_ALLOWED_ADDRESSES, MEET_ZONE; carlos relay enable --app |
| +meet; migrations apply at boot once each (log line msg=migrate); every |
| +deploy restarts the instance and drops live calls, so deploy outside |
| +meeting hours; the canary recipe (carlos instances create + carlos deploy |
| +--channel) because carlos canary forms a two-label host, platform #124.> |
| + |
| +## Where things are written down |
| +<spec, programme plan, the slice records under docs/superpowers/reviews/, |
| +PRODUCT.md, AGENTS.md.> |
| +``` |
| + |
| +- [ ] **Step 3: Append to `AGENTS.md`**, after the "Serving" section, a "Deploying" section of at most eight lines: unit route; `carlos deploy` with the probe; migrations at boot, never re-run (already in the rules; say only that a database which applied a differently named migration file fails at boot); every deploy and every relay config change restarts the instance and drops live calls; the `carlos deploy` wait can time out before the hand-over, check `/api/version` before retrying; the canary recipe. No other change to AGENTS.md. |
| + |
| +- [ ] **Step 4: Check** `grep -c '' README.md` is under 140 lines, no sentence claims something you did not verify, no suite ruling is paraphrased where a number will do. |
| + |
| +- [ ] **Step 5:** Do not commit. Report the claim list. |
| + |
| +### Task 2: PRODUCT.md |
| + |
| +**Files:** |
| +- Create: `PRODUCT.md` |
| + |
| +**Interfaces:** |
| +- Consumes: `oficina/docs` `PRODUCT.md` as the shape (impeccable product schema 1: Platform, Users, Product Purpose, Positioning, Operating Context, Capabilities and Constraints, Brand Commitments, Evidence on Hand, Product Principles, Accessibility & Inclusion), the spec's §1 (goals), §9 (the floor), §11 (deliberately not built), §13 (gates), the slice records. |
| +- Produces: the section "What is deliberately not here" that spec §9 says slice 6 records the scriptless exception in. |
| + |
| +- [ ] **Step 1: Read** `/home/paulca/amadan.net/oficina/docs/PRODUCT.md` in full for the shape and the disclaimer header (written unattended; facts cited to spec or code; readings marked **[inferred — confirm]**). |
| + |
| +- [ ] **Step 2: Write `PRODUCT.md`** in that shape, for Meet, citing spec sections and files. It must contain a section **"What is deliberately not here"** listing: the scriptless-floor exception (browser media participation, spec §9); no reactions, dial-in, captions, multi-host signalling, recordings (§11, as amended on main); no STUN/TURN of Meet's own (ruling 6); no passkeys at the instance (as Docs); no SFU (roadmap 4b later); no client-address limiter on the API (§15.17); chat never stored; the room capped at four. Mark inferred readings. Under 240 lines. |
| + |
| +- [ ] **Step 3:** Do not commit. Report the claim list. |
| + |
| +### Task 3: The *Consumed suite rulings* commit and §15.18 |
| + |
| +**Files:** |
| +- Modify: `docs/superpowers/specs/2026-09-07-meet-design.md` (§0.2; §12 item 6; a new §15.18) |
| + |
| +**Interfaces:** |
| +- Consumes: doctrine main `1ac4323` revision 8 (`/home/paulca/amadan.net/oficina/suite/docs/superpowers/specs/2026-09-05-suite-sharing-doctrine.md`, verified current by `git ls-remote` on 2026-09-14), Appendix A's intro (name the ruling, delete the restatement), spec §7.1.1 and the 2026-09-12 sharing amendment on main, `internal/meet/home.go`, `internal/meet/api.go`. |
| +- Produces: the commit suite Appendix A.6 will cite (its hash goes on suite discussion 5 in Task 4). |
| + |
| +- [ ] **Step 1: Refresh §0.2.** Keep the table's shape. Confirm the doctrine citation (revision 8 at 1ac4323, still main on 2026-09-14). Update the row for rulings 4 and 12: the home now mints assertions and Meet consumes them through `home/connect` (§7.1.1) while the allowlist remains the membership authority; the row must name the rulings and §7.1.1, not restate them. Add a row for ruling 16 as amended by the 2026-09-12 sharing update (invitation tokens are hash-indexed with a sealed copy for members' repeat sharing; agent credentials remain hash-only and shown once). Keep "Also consumed" current (discussion 4; the media roadmap; the relay spec, now live). Do not paraphrase any ruling. |
| + |
| +- [ ] **Step 2: §12 item 6:** annotate as delivered on 2026-09-14 with the disposition table from this plan's "What slice 6 was" section in one sentence per item. |
| + |
| +- [ ] **Step 3: Add §15.18** "§12 item 6 — what slice 6 delivered, deferred and declined": the README and PRODUCT.md; the acknowledgements page deferred to discussion 10's branch; the Estilo pin (no tag exists; adopted at a pseudo-version by the Home integration on main; the programme's condition is recorded as unmet and the adoption as done by another route); no deploy from a docs-only slice, edge hand-managed at 651cff2. |
| + |
| +- [ ] **Step 4:** Do not commit. Report the exact lines changed. |
| + |
| +### Task 4: Record, reviews, merge, notification |
| + |
| +**Files:** |
| +- Create: `docs/superpowers/reviews/2026-09-14-slice-6-record.md` |
| + |
| +- [ ] **Step 1:** Commit Tasks 1 to 3 as three commits (README+AGENTS; PRODUCT.md; "Consumed suite rulings: §0.2 against doctrine 1ac4323 rev 8, §15.18"). |
| +- [ ] **Step 2:** Whole-branch review (Opus): every claim in the three documents checked against the code on the branch; findings W6-n. |
| +- [ ] **Step 3:** Codex round(s) until accept. |
| +- [ ] **Step 4:** Record in the shape of the slice 5 record: rulings, dispositions, carried items (the acknowledgements page, the Estilo tag, the production promotion, the credits inventory freshness gate that discussion 10 adds), the copy catalogue note, the gates (`make ci` on the head; the browser gate is not run: no page or client changed). |
| +- [ ] **Step 5:** `make ci`, push, remote CI, fast-forward main, the notification on `oficina/meet` discussion 3 and the checkpoint on `oficina/suite` discussion 5 naming the §0.2 commit for Appendix A.6, close the slice discussion, hub tasks Done, memory. |