Update 3tk examples

Author: g41797

design/STATUS.md

@@ -39,7 +39,7 @@ instruction, read this file and ask what to work on.
 ## Rules
 - Read STATUS.md in full each session. It says where we are and what is next.
 - Session Log lives in STATUS-LOG.md (append-only, newest entries at top). Do NOT read it by default — append new entries there without reading the rest. Read STATUS-LOG.md only when explicitly asked (history audit, "what did we do about X", resolving a specific past-decision question).
-- No git directly. Owner does git.
+- No git directly, in this or any other repo. Owner does git. Exception: plain `git status` may be run without asking; every other git command still needs the owner or explicit one-off approval.
 - No skipping stages. Each stage passes before the next.
 - No real code before infrastructure (Stage 0) is verified.
 - Show intent before code changes. Get owner approval.
@@ -53,7 +53,7 @@ instruction, read this file and ask what to work on.
 - Status file ownership. A fact lives in exactly one file; the others get a pointer, not a copy. STATUS.md = current state only, no stage narrative. Plan = forward-looking work + one line per completed stage. STATUS-LOG.md = the narrative. context.md = one short line per doc, saying what it is. Full entry in rules-049.md.
 
 ## Constraints for Next Agent (MUST)
-- Git disabled. Do NOT run any git commands.
+- Git disabled, in every repo, always. Do NOT run any git commands except plain `git status`, which is allowed on its own.
 - Coding style: LE imports, explicit types, explicit dereference, stdlib first, errdefer/defer for resource cleanup.
 - Doc style: short sentences, bullets, no AI-sh words. See plan Section 1.
 - Run verification via kitchen scripts, not manual zig commands.

design/secondary/lang/c3/3tk-log.md

@@ -7,6 +7,83 @@ Current state is in [3tk-status.md](3tk-status.md).
 
 ---
 
+## 2026-08-31 — 3TK-57 follow-up: docs.yml now deploys to Pages
+
+**The Pages-collision question 3TK-57 left open is resolved — not by a
+ruling, but by the repo split itself.** The blocker was: *"this repo's Pages
+deployment already belongs to ztk's `docs.yml`. A second workflow calling
+`deploy-pages` without coordination would clobber it."* That was true only
+while both workflows lived in `matryoshka-tk`. Once 3tk's CI moved to its own
+repo, `matryoshka-3tk`, there is no second workflow in the same repo to
+clobber — ztk's Pages deployment is in a different repo entirely.
+
+**`matryoshka-3tk/.github/workflows/docs.yml` gained a `deploy` job**, added
+after the owner reviewed external advice (correct in shape, but guessed at
+`c3c docgen`'s output rather than checking it):
+
+- `docgen` job unchanged through the `c3c docgen --emit-stdlib=no src
+  examples` step, still no mkdocs and no `kitchen/tools/*.sh` equivalent —
+  plan 021 was explicit that there is nothing for the docs workflow to wrap
+  beyond that one command.
+- A new "Prepare Pages site" step: `mkdir site && cp docs.html
+  site/index.html`. `c3c docgen` writes one self-contained `docs.html` into
+  the current directory — `preview-docs.sh`'s own comment says so — not a
+  directory, so `actions/upload-pages-artifact@v3` (which needs a directory
+  with `index.html` at its root) can't point at `docs.html` directly.
+- `actions/upload-pages-artifact@v3` replaces the plain `actions/upload-artifact@v4`
+  step; a separate `deploy` job (`needs: docgen`, `permissions: {pages:
+  write, id-token: write}`, `environment: github-pages`) calls
+  `actions/deploy-pages@v4`.
+
+**Still the owner's step, not run here:** enabling Pages on `matryoshka-3tk`
+(Settings → Pages → Source: GitHub Actions) before the workflow's `deploy`
+job can succeed.
+
+## 2026-08-31 — 3TK-57: GitHub Actions CI, built in `matryoshka-3tk`
+
+Plan 021 declared `.github/workflows/3tk-linux.yml`, `3tk-sanitizers.yml`,
+`3tk-docs.yml` and README badges here, in `matryoshka-tk`, scoped with
+`paths:`/`working-directory` to `design/secondary/lang/c3/3tk/**` — the same
+pattern ztk's own workflows use in this repo.
+
+**The owner corrected that placement mid-stage: every 3tk workflow belongs in
+`matryoshka-3tk` (local path `~/dev/root/github.com/g41797/matryoshka-3tk`),
+not here.** That repo is 3tk's own tree — `src/`, `test/`, `negative/`,
+`examples/`, `project.json` and `scripts/{run-builds,run-sanitizers,preview-docs}.sh`
+all live at its root, mirroring how ztk's repo owns its own `.github/`. The
+first draft, written directly into `matryoshka-tk/.github/workflows/`, was
+removed and rewritten there instead.
+
+**Written, in `matryoshka-3tk`:**
+
+- `.github/workflows/linux.yml` — push/pull_request/workflow_dispatch,
+  `c3c build mtk` + `c3c test`, matrix `safe:[yes,no] × opt:[O0,O3]`, matching
+  `scripts/run-builds.sh`'s four `MODES`. No `paths:` or
+  `working-directory` needed — the whole repo is 3tk.
+- `.github/workflows/sanitizers.yml` — `workflow_dispatch` only, installs
+  clang via `apt-get`, then `c3c test --sanitize=<thread|address> --cc clang`
+  for the same three combinations `scripts/run-sanitizers.sh` runs (`thread
+  safe-O0`, `thread fast-O3`, `address safe-O0`), 15-minute timeout per job.
+- `.github/workflows/docs.yml` — push to `main` on `src/**`/`examples/**`
+  plus `workflow_dispatch`; `c3c docgen --emit-stdlib=no src examples`,
+  uploaded as a build artifact, not deployed to Pages (the open
+  coexistence question with ztk's Pages deployment is unchanged by this).
+- Three README badges added to `matryoshka-3tk/README.md`, which had none
+  before.
+
+**Installing c3c**, same in every workflow, verified against the live GitHub
+API for `v0.8.3` before being written rather than assumed: the Linux asset is
+`c3-linux.tar.gz`, confirmed to extract to `c3/` containing `c3/c3c` — fetched
+and inspected with `curl`/`tar tzf`, not recalled from memory.
+
+**No stage ran `git`.** All six files (three workflows, one README edit) were
+written directly; nothing was staged, committed, or pushed in either repo. The
+owner saves and pushes both.
+
+**A memory record was added** (`3tk-ci-lives-in-matryoshka-3tk` in Claude's
+memory) so a future 3tk CI/workflow task starts from the corrected repo
+without repeating this correction.
+
 ## 2026-08-31 — 3TK-50 step 9: Shutdown, entries 46–48
 
 **Catalog section "Shutdown."** One of the three entries carries a code

design/secondary/lang/c3/3tk-staging-plan-021.md

@@ -0,0 +1,148 @@
+# 3tk — staging plan 021
+
+Written 2026-08-31.
+
+**Provenance.** Follows [3tk-staging-plan-020.md](backup/3tk-staging-plan-020.md). 020
+carried **3TK-50** forward unchanged and declared **3TK-51 to 3TK-55**. All of
+that has since run — 3TK-50 closed across eleven steps (`3tk-log.md`, 2026-08-31),
+3TK-51 through 3TK-55 all ran 2026-08-28, and **3TK-56 also ran** (2026-08-30,
+closing `P6`) without a separate declaration, since it fell directly out of
+3TK-54's own measurement. **020 is fully spent.** This plan declares one stage:
+**3TK-57.**
+
+State is in [3tk-status.md](3tk-status.md). Narrative is in
+[3tk-log.md](3tk-log.md). Neither is duplicated here.
+
+---
+
+## Why this plan exists
+
+**Everything 3tk builds and tests locally — `run-builds.sh`'s four modes,
+`run-sanitizers.sh`'s three sanitizer runs — has no automated check on a push
+or a pull request.** The owner asked for GitHub Actions workflows, patterned on
+the ones already in this repo for ztk (`.github/workflows/linux.yml`,
+`mac.yml`, `windows.yml`, `docs.yml`), but adapted: c3c has no `setup-c3`
+action the way Zig has `mlugg/setup-zig`, 3tk's toolchain is measured only on
+linux-x64, and the owner does not want CI invoking `run-builds.sh` or
+`run-sanitizers.sh` as scripts — the workflows replicate their underlying
+commands directly as steps, the same way ztk's workflows call `zig build test`
+directly rather than through a wrapper.
+
+**Four decisions the owner made, binding on 3TK-57:**
+
+1. **Linux only.** No macOS/Windows legs — the port calls pthread directly and
+   has never been tried on either.
+2. **Sanitizers in their own file, manually triggered** (`workflow_dispatch`
+   only, never push/PR), installing their own compiler (clang) rather than
+   assuming the runner has it.
+3. **Negatives, tier-1 aborts and nocompile checks stay local-only.** CI runs
+   build+test per mode; `run-builds.sh` remains the full local gate.
+4. **The docs workflow does only the `c3c docgen` flow** — no mkdocs, no
+   `kitchen/tools/*.sh` equivalent. `c3c docgen` already produces a complete,
+   self-contained doc site; there is nothing for it to wrap.
+
+**One call flagged for the owner to override, not yet resolved:** this repo's
+Pages deployment already belongs to ztk's `docs.yml`. A second workflow
+calling `deploy-pages` without coordination would clobber it. **3TK-57's docs
+workflow builds and uploads the `c3c docgen` output as a workflow artifact
+only — it does not deploy to Pages** until the owner decides how the two doc
+sets should coexist on one site.
+
+## The stage
+
+```
+3TK-57   GitHub Actions CI for 3tk      .github/workflows/ + README.md
+```
+
+**Why one stage and not several.** Unlike 3TK-51–55, nothing here is staged on
+an unresolved design question — the four decisions above are already made, and
+the three workflow files have no dependency order between them. Splitting them
+into separate stages would only fragment one afternoon's work across several
+clear points for no reason the *Five stages means five clear points* logic in
+020 actually needed.
+
+---
+
+## 3TK-57 — GitHub Actions CI for 3tk
+
+**Output: three new workflow files, plus three README badges.**
+
+| file | trigger | what it does |
+|---|---|---|
+| `.github/workflows/3tk-linux.yml` | push, pull_request, workflow_dispatch; `paths: design/secondary/lang/c3/3tk/**` | `c3c build mtk` + `c3c test`, matrix `safe:[yes,no] × opt:[O0,O3]` — the same four combinations as `run-builds.sh`'s `MODES` |
+| `.github/workflows/3tk-sanitizers.yml` | workflow_dispatch only | installs clang, then `c3c test --sanitize=<thread\|address> --cc clang` for the same three combinations `run-sanitizers.sh` runs (`thread safe-O0`, `thread fast-O3`, `address safe-O0`), 15-minute timeout per run |
+| `.github/workflows/3tk-docs.yml` | push to `main` with `paths` on `3tk/src/**` and `3tk/examples/**`, plus workflow_dispatch | `c3c docgen --emit-stdlib=no src examples`, uploaded as a build artifact — not deployed |
+
+**Installing c3c.** No `setup-c3` action exists. Confirmed against the GitHub
+API: `v0.8.3`'s Linux asset is `c3-linux.tar.gz`, which extracts to `c3/`
+containing `c3/c3c` and a bundled `c3/lib/std/` — self-contained, matching the
+version 3tk's own capability answers are measured against
+(`3tk-status.md`: "c3c 0.8.3, LLVM 22.1.8, linux-x64"). Every workflow installs
+it the same way:
+
+```yaml
+- name: Install c3c
+  run: |
+    curl -sL https://github.com/c3lang/c3c/releases/download/v0.8.3/c3-linux.tar.gz -o c3.tar.gz
+    tar xzf c3.tar.gz
+    echo "$PWD/c3" >> "$GITHUB_PATH"
+```
+
+**Every 3tk workflow scopes itself.** Unlike ztk's workflows, which own the
+whole repo, each 3tk file needs `paths:` (where it triggers on push/PR) and a
+job-level `working-directory: design/secondary/lang/c3/3tk`, since 3tk is one
+subtree in a multi-port repo.
+
+**README.md gains 3 more badges**, top of file alongside the existing 4, one
+per new workflow, same style: `.../actions/workflows/<file>.yml`.
+
+**Tests, and the stage does not close without them checked:**
+
+- Each new workflow file parses as valid YAML.
+- Every command in every workflow matches, field for field, what
+  `run-builds.sh` / `run-sanitizers.sh` / `preview-docs.sh` actually run —
+  checked against their source, not paraphrased.
+- The c3c download step is verified against the live GitHub API response for
+  `v0.8.3` (asset name, extracted layout) before being written into the
+  workflow files, not assumed.
+
+**What is not verified from here, and is the owner's step once pushed:** that
+the c3c download step actually succeeds on `ubuntu-latest`, and that
+`apt-get install clang` on `ubuntu-latest` pulls in whatever `libtsan`/`libasan`
+the sanitizer runs need — unlike this Fedora machine, which is missing them
+under its default `cc`. **No stage runs `git`.** The files are written; the
+owner pushes and watches the first run.
+
+---
+
+## Rules that hold
+
+- **`run-builds.sh` stays green throughout** — nothing in 3TK-57 touches
+  `3tk/src`, `test/`, `negative/` or `examples/`, so the counts do not move.
+- **No stage runs `git`.** Moves are plain `mv`. The owner saves and pushes.
+- **A claim about c3c is measured, never argued** — the download URL and
+  tarball layout above were fetched and inspected, not assumed from memory.
+- **The Pages-collision question is written down, not guessed at.** 3TK-57
+  does not deploy to Pages; it stops at "build and upload as a workflow
+  artifact" and leaves the coexistence question open.
+
+## Versioning
+
+**`3tk-staging-plan-020.md` is superseded by this file** and moves to
+`backup/`. Nothing else this stage produces is a versioned document —
+`.github/workflows/*.yml` and `README.md` are edited in place, same as any
+other source file a stage touches.
+
+## What this plan leaves to the owner
+
+- **The Pages-collision question.** A subpath, a merge step before one
+  `deploy-pages` call, a separate deployment mechanism (e.g.
+  `peaceiris/actions-gh-pages` targeting a subfolder of `gh-pages`) — or 3tk's
+  docs staying artifact-only indefinitely. Not decided here.
+- **Whether macOS/Windows legs ever get added**, and who confirms the port
+  actually builds there first.
+- **Whether sanitizers stay manual-only**, or graduate to a scheduled or
+  push-triggered run once the workflow has been exercised a few times.
+- **The seven questions plan 018 left and 019 carried**, and everything in
+  `3tk-status.md`'s *Open questions* — untouched by this stage, and not
+  reopened by it.

design/secondary/lang/c3/3tk-status.md

@@ -515,6 +515,7 @@ not the record.
 | **3TK-52** | the shared clause: closed and quiet, and specification 005 | 2026-08-28 |
 | **3TK-55** | the defect list catches up with the code | 2026-08-28 |
 | **3TK-56** | the close hook takes the queue by value, and `P6` is closed | 2026-08-30 |
+| **3TK-57** | GitHub Actions CI — built in `matryoshka-3tk`, not here | 2026-08-31 |
 
 **3TK-50 is missing from the list because it has not run** — it is plan 019's
 leftover and is in the table above.