# AI tech-writer — getting started

> Generated by `beadloom setup-ai-techwriter`. Re-run that command to refresh
> the scaffolded files (CI wrapper, operator artifacts, this guide); do not
> hand-edit them.

The **AI tech-writer** keeps your docs honest: on every **pull/merge request to
`main`/`master`** (or on demand via `workflow_dispatch`) it finds docs that have
drifted from the code (`beadloom sync-check`), has a Goose agent rewrite each
drifted doc against the current code, proves freshness with Beadloom's own gate
(`beadloom ci`), and — on the PR path — **commits the refresh straight back into
the PR branch** for human review (the manual path cuts a branch + opens a PR).
Each run resolves to one verdict: `ok` (clean / no-op), `flagged` (the model ran
but docs still aren't clean → check red, PR blocked), or `infra` (the agent
never produced output → check stays green with a loud warning). It never
auto-merges — `sync-check → 0` proves *freshness*, only a human proves
*correctness*.

## What `setup-ai-techwriter` dropped into this repo

- The harness itself ships **inside the installed `beadloom` package** — no
  vendored code is dropped into your repo. The CI wrapper invokes it via
  `python -m beadloom.ai_agents.ai_techwriter` (your repo only needs `beadloom`
  + `goose` + python on the runner).
- `tools/ai_techwriter/recipe.yaml` — the Goose recipe (operator artifact,
  copied from the `beadloom` package so you can tweak it locally).
- `tools/ai_techwriter/provision-runner.sh` — a hardened, **idempotent** script
  that stands up the self-hosted VPS runner for you (swap-first, RAM/disk
  prechecks, fail-hard on the critical steps). See the box below.
- The CI wrapper for your platform:
  - GitHub: `.github/workflows/ai-techwriter.yml`
  - GitLab: the `ai-techwriter` job in `.gitlab-ci.yml`
- This guide (`docs/guides/ai-techwriter.md`).

## 3-step setup

1. **Pick the box (≥ 4 GB RAM).** The agent job runs
   `uv sync --extra dev --extra languages` + a reindex; a 1 GB box OOMs (we
   watched one kill sshd mid-provision). An **8 GB / 4 CPU** box is the
   proven-good size; the script refuses below ~2 GB and needs ~5 GB free disk.
2. **Get a runner registration token** — GitHub:
   *Settings → Actions → Runners → New self-hosted runner* (or let the script
   fetch one if `gh` is authenticated on the box); GitLab: the project's
   *Settings → CI/CD → Runners* registration token. Also add the **`QWEN_API_KEY`**
   secret (GitHub repository secret / GitLab masked CI/CD variable) — referenced
   only by name in the wrapper, resolved on the runner, never written into the
   repo. Optionally set `QWEN_BASE_URL` the same way to point at a
   workspace-specific MaaS endpoint (defaults to the DashScope gateway).
3. **Provision the runner**, then commit + enable. On the VPS run:

   ```bash
   ./tools/ai_techwriter/provision-runner.sh \
     --platform <github|gitlab> --repo <repo-url> --token <reg-token>
   ```

   The script guarantees swap before any apt/build, installs the base toolchain
   + the runner, **registers** it (labels/tags `self-hosted,ai-techwriter`) and
   starts the service — fail-hard on those critical steps. Goose / beadloom / bd
   are installed best-effort and **verified + reported** at the end (it never
   aborts the runner setup for them; install any that report MISSING). It is
   safe to re-run. The token is passed by `--token` (or the `REG_TOKEN` env var)
   and is never written into the repo. Then **commit** the scaffolded files and
   **enable the pipeline** (GitHub: on once committed; GitLab: runs on push to
   main/master, or run it manually from the web).

After that the loop runs on push to main/master (+ manual) and opens PRs/MRs.
Nothing else
is configured per-repo — the harness + recipe are repo-agnostic and read *this*
repo's own graph + docs.

## Cost & safety

- **Quality first, scope-bounded cost.** Extended thinking stays on; cost is
  bounded by scope (only drifted docs + scoped context) plus generous runaway
  hard caps (max turns / tokens / wall-clock), never by capping reasoning.
- **Small blast radius.** The agent may write only `docs/**`, runs no arbitrary
  shell, and never marks docs synced or merges — those steps are deterministic
  and owned by the harness + the human reviewer.
- **No secrets in logs;** the key lives only on the runner.

## Updating

Re-run `beadloom setup-ai-techwriter --platform <github|gitlab>` to refresh the
CI wrapper, the operator artifacts (recipe + provisioner), and this guide to the
version shipped with your installed `beadloom` (the harness itself is upgraded
just by upgrading the `beadloom` package). The re-run is idempotent (a clean
overwrite of the generated files).
