| 1 | # Meet Slice 6: Deploy Docs Implementation Plan |
| 2 | |
| 3 | > **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. |
| 4 | |
| 5 | **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. |
| 6 | |
| 7 | **Architecture:** Documentation only. Nothing under `internal/`, `native/`, `callscore/` 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. |
| 8 | |
| 9 | **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`. |
| 10 | |
| 11 | **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). |
| 12 | |
| 13 | ## Global Constraints |
| 14 | |
| 15 | - Branch `slice/6-deploy` from main `9225ec2`; docs only; `make ci` stays green (it is unaffected by Markdown, run it once at the end). |
| 16 | - 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. |
| 17 | - 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. |
| 18 | - 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). |
| 19 | - Nothing here restates a suite ruling; §0.2 names rulings by number (doctrine Appendix A intro: "delete the restatement, name the ruling"). |
| 20 | |
| 21 | ## What slice 6 was, and what it is now |
| 22 | |
| 23 | 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/calls/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/`, `callscore/`, `protocol/`, tag `v0.1.0` at `9225ec2`). Therefore: |
| 24 | |
| 25 | | Programme item | Disposition in this slice | |
| 26 | |---|---| |
| 27 | | PRODUCT.md | Task 2, here. | |
| 28 | | README with floor and relay paragraphs first | Task 1, here. | |
| 29 | | AGENTS.md final notes | Task 1, here (deploy and gate notes only; the file already carries the native and sharing notes added on main). | |
| 30 | | 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. | |
| 31 | | 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. | |
| 32 | | 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. | |
| 33 | | Production promotion with its notification | **No deploy from this slice.** The change is documentation; edge (`calls.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). | |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | ### Task 1: README.md and AGENTS.md's final notes |
| 38 | |
| 39 | **Files:** |
| 40 | - Create: `README.md` |
| 41 | - Modify: `AGENTS.md` (append a short "Deploying" section after "Serving"; do not touch existing lines) |
| 42 | |
| 43 | **Interfaces:** |
| 44 | - Consumes: spec §3.3/§3.4 (the floor sentence on the holding page and room: find the exact shipped sentence in `internal/calls/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/calls/main.go` (env vars), `internal/calls/config.go` (which are refused when empty outside development). |
| 45 | - Produces: the README that PRODUCT.md (Task 2) and the record (Task 4) link to. |
| 46 | |
| 47 | - [ ] **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. |
| 48 | |
| 49 | - [ ] **Step 2: Write `README.md`** with this shape (the paragraphs in this order; write them as prose, not as this outline): |
| 50 | |
| 51 | ```markdown |
| 52 | # Meet |
| 53 | |
| 54 | <Paragraph 1: what Meet is (video calls for one team: create or schedule a |
| 55 | meeting, share a link, a holding screen, a room of up to four, chat, screen |
| 56 | share, an agent API), and the floor sentence: every screen works with |
| 57 | JavaScript disabled except browser media participation, the camera preview |
| 58 | and join button on the holding screen and the call itself in the room; both |
| 59 | pages render their title, standing, floor notice and navigation without |
| 60 | script (spec §9).> |
| 61 | |
| 62 | <Paragraph 2: the relay. ICE servers come from the CARLOS platform relay, |
| 63 | delivered as CARLOS_RELAY and minted per call at GET /m/{sqid}/ice; Meet |
| 64 | names no STUN or TURN server of its own (suite ruling 6); with no relay |
| 65 | configured, calls are direct only and the holding screen says so. Enabling |
| 66 | or rotating the relay restarts the instance (spec §5.2, §5.5, §15.13).> |
| 67 | |
| 68 | ## Sign-in |
| 69 | <magic link to an allowlisted address (CALLS_ALLOWED_ADDRESSES); a meeting |
| 70 | link gives an outsider a guest grant at sign-in, never a way in without a |
| 71 | name; optional Home sign-in with the four CALLS_HOME_* settings, all or |
| 72 | none (spec §7.1.1).> |
| 73 | |
| 74 | ## The room |
| 75 | <P2P mesh of up to four, perfect negotiation, SSE stream + POST signal, |
| 76 | waiting queue for guests, removal and takeover through confirm pages, |
| 77 | chat fanned out and never stored, screen share as a second tile; every |
| 78 | deploy drops live calls because the hub is in-process (spec §4, §5, §6).> |
| 79 | |
| 80 | ## Agents |
| 81 | <Settings mints a token shown once; bearer-only /api/v1 (list, create, |
| 82 | replace links, end, get); reach re-derived per request; 60/min per agent; |
| 83 | spec §8 and §15.17.> |
| 84 | |
| 85 | ## Native apps |
| 86 | <one paragraph pointing at native/README.md and native/ios/README.md; |
| 87 | make native-mac; same server and shared Go core; no embedded webviews.> |
| 88 | |
| 89 | ## Building and gates |
| 90 | <make ci (CGO_ENABLED=0), make race (the cgo exception, tests only), |
| 91 | make browser (real Chromium, 31+ scenarios, about nine minutes, must run |
| 92 | with the Claude Code bash sandbox off: UDP is blocked inside it), make |
| 93 | native-test; make release VERSION=<sha> stamps /api/version.> |
| 94 | |
| 95 | ## Deploying |
| 96 | <unit route on CARLOS; carlos deploy --app meet --account oficina with the |
| 97 | build probe on /api/version; secrets CALLS_INSTANCE_KEY, CALLS_DEK (32 base64 |
| 98 | bytes), mail via CALLS_SMTP_* with CARLOS_SMTP_* as fallback; env |
| 99 | CALLS_ORIGIN, CALLS_ALLOWED_ADDRESSES, CALLS_ZONE; carlos relay enable --app |
| 100 | meet; migrations apply at boot once each (log line msg=migrate); every |
| 101 | deploy restarts the instance and drops live calls, so deploy outside |
| 102 | meeting hours; the canary recipe (carlos instances create + carlos deploy |
| 103 | --channel) because carlos canary forms a two-label host, platform #124.> |
| 104 | |
| 105 | ## Where things are written down |
| 106 | <spec, programme plan, the slice records under docs/superpowers/reviews/, |
| 107 | PRODUCT.md, AGENTS.md.> |
| 108 | ``` |
| 109 | |
| 110 | - [ ] **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. |
| 111 | |
| 112 | - [ ] **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. |
| 113 | |
| 114 | - [ ] **Step 5:** Do not commit. Report the claim list. |
| 115 | |
| 116 | ### Task 2: PRODUCT.md |
| 117 | |
| 118 | **Files:** |
| 119 | - Create: `PRODUCT.md` |
| 120 | |
| 121 | **Interfaces:** |
| 122 | - 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. |
| 123 | - Produces: the section "What is deliberately not here" that spec §9 says slice 6 records the scriptless exception in. |
| 124 | |
| 125 | - [ ] **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]**). |
| 126 | |
| 127 | - [ ] **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. |
| 128 | |
| 129 | - [ ] **Step 3:** Do not commit. Report the claim list. |
| 130 | |
| 131 | ### Task 3: The *Consumed suite rulings* commit and §15.18 |
| 132 | |
| 133 | **Files:** |
| 134 | - Modify: `docs/superpowers/specs/2026-09-07-meet-design.md` (§0.2; §12 item 6; a new §15.18) |
| 135 | |
| 136 | **Interfaces:** |
| 137 | - 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/calls/home.go`, `internal/calls/api.go`. |
| 138 | - Produces: the commit suite Appendix A.6 will cite (its hash goes on suite discussion 5 in Task 4). |
| 139 | |
| 140 | - [ ] **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. |
| 141 | |
| 142 | - [ ] **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. |
| 143 | |
| 144 | - [ ] **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. |
| 145 | |
| 146 | - [ ] **Step 4:** Do not commit. Report the exact lines changed. |
| 147 | |
| 148 | ### Task 4: Record, reviews, merge, notification |
| 149 | |
| 150 | **Files:** |
| 151 | - Create: `docs/superpowers/reviews/2026-09-14-slice-6-record.md` |
| 152 | |
| 153 | - [ ] **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"). |
| 154 | - [ ] **Step 2:** Whole-branch review (Opus): every claim in the three documents checked against the code on the branch; findings W6-n. |
| 155 | - [ ] **Step 3:** Codex round(s) until accept. |
| 156 | - [ ] **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). |
| 157 | - [ ] **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. |
| 158 | |
amadan