From 6343fd012d04cd50706c0de2cd968a599747d745 Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 26 Oct 2026 05:28:45 +0000 Subject: [PATCH] docs: state-root, contributor reference and capy-install follow the launch-file contract (Step 14.5 audit) The /document-release audit (docs-3449-1792992068) corrected three authored docs: docs/state-root.md shows the GSTACK_LAUNCH_FILE line and says to apply it with ". " instead of prefixing or exporting the assignments; docs/CONTRIBUTOR_REFERENCE.md names scan()'s one ambient input instead of calling it pure; docs/capy-install.md's bun-shim bullet and exit table name the launch file and the fail launch-file trailer. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/CONTRIBUTOR_REFERENCE.md | 5 ++++- docs/capy-install.md | 6 +++--- docs/state-root.md | 10 +++++++--- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/CONTRIBUTOR_REFERENCE.md b/docs/CONTRIBUTOR_REFERENCE.md index b6b89d996..2146411ed 100644 --- a/docs/CONTRIBUTOR_REFERENCE.md +++ b/docs/CONTRIBUTOR_REFERENCE.md @@ -111,7 +111,10 @@ determined leaker (a CHANGELOG line that does would fail a hostile screenshotter - **Engine + taxonomy:** `lib/redact-patterns.ts` (the single source of truth — 3 tiers; HIGH = genuinely-secret credentials that block, MEDIUM = PII/legal/ internal + high-FP credential shapes that confirm via AskUserQuestion, LOW = - FYI) and `lib/redact-engine.ts` (pure `scan()` + `applyRedactions()`). + FYI) and `lib/redact-engine.ts` (`scan()` + `applyRedactions()`; no I/O, + and `scan()`'s one ambient input is the credential-named variables of + `process.env`, read by value for the `env.value` HIGH finding unless + `ScanOptions.processEnv` names another environment). Calibration matters: a gate that cries wolf gets ignored, so context-variable shapes (Stripe `pk_live_`, Google `AIza`, JWT, env `*_KEY=`) sit at MEDIUM. - **CLI:** `bin/gstack-redact` (exit 0 clean / 2 MEDIUM / 3 HIGH; `--json`, diff --git a/docs/capy-install.md b/docs/capy-install.md index e1c4afd0e..8df31b149 100644 --- a/docs/capy-install.md +++ b/docs/capy-install.md @@ -254,8 +254,8 @@ through the `bun` shim beside it. - `GSTACK_BUN_SHIM=0` at install time writes no shim. - Removing it: delete `~/.local/bin/bun` and `~/.local/bin/bunx`. gstack replaces only a missing file or a file carrying the marker; a foreign file - or a dangling link there is left untouched with a note, and the - `GSTACK_LAUNCH` prefix stays the way to reach the certified Bun. + or a dangling link there is left untouched with a note, and sourcing the + launch file (`. `) stays the way to reach the certified Bun. - The doctor's `runtime` row notes the shim; the resolver never treats a shim-marked file as a Bun candidate. @@ -448,6 +448,6 @@ Wrapper 2 only adds optional exports (the trailer's `latest:` note and the | Exit | Meaning | |-----:|---------| | 0 | `gstack: ok` — every required component passed | -| 1 | `gstack: fail ` — a required component failed; each row has a fix | +| 1 | `gstack: fail ` — a required component failed; each row has a fix. Also `gstack: fail launch-file …` when a passing run could not write its launch file ([LAUNCH_FILE_UNWRITABLE](troubleshooting.md#capy-install-launch-file-unwritable)) | | 2 | usage error | | 3 | preflight stopped before `./setup` (`INSTALL_PREFLIGHT_FAILED`, `RUNTIME_PIN_CONFLICT`); nothing was installed | diff --git a/docs/state-root.md b/docs/state-root.md index 45c246ec6..376261884 100644 --- a/docs/state-root.md +++ b/docs/state-root.md @@ -166,14 +166,18 @@ option and never writes there. A child shell's `export` cannot configure the parent's later commands (`lib/state-root.ts` reads each process's own environment), so the installer ends with one machine-readable line the parent supplies to every gstack -command it launches: +command it launches, and the same assignments as a sourceable file: ``` GSTACK_LAUNCH: GSTACK_SESSION_KIND=unattended GSTACK_STATE_ROOT= GSTACK_EPHEMERAL=1 +GSTACK_LAUNCH_FILE: .env ``` -Prefix each command with those assignments (or export them once in the shell -that runs them). See [docs/capy-install.md](capy-install.md). +Apply them with `. ` at the start of the shell that runs each +command; never re-type them as `export $(...)`, and never run `env`, `printenv`, +a bare `set` or a bare `export` in a tool fence (a bare `export` prints every +variable, credentials included). See +[docs/capy-install.md](capy-install.md#the-launch-line). ## Uninstall