crewforth 0.0.1 → 3.0.0-rc.1

package/kit/skills/db-migration/references/tool-matrix.md

@@ -0,0 +1,35 @@
+# Tool × life-cycle commands
+
+Find your tool's row and use it. A project has one migration tool; the other eight rows are noise at the
+moment you are running a migration, which is why they are here rather than in `SKILL.md`.
+
+The sequence itself — **Preview → (approval) → Apply → Verify** — and the rule that a destructive migration
+never skips the approval gate live in `SKILL.md`. This file only says which command spells each step.
+
+| Tool | Status | Preview (dry-run) | Apply | Verify | Roll back |
+|---|---|---|---|---|---|
+| Prisma | `migrate status` | `migrate diff … --script` | `migrate deploy` | `migrate status` | `migrate resolve --rolled-back` + backup |
+| Knex | `migrate:status` | `migrate:latest --dry-run` | `migrate:latest` | `migrate:status` | `migrate:rollback` |
+| Sequelize | `db:migrate:status` | read the migration file | `db:migrate` | `db:migrate:status` | `db:migrate:undo` |
+| TypeORM | `migration:show` | read the pending file | `migration:run` | `migration:show` | `migration:revert` |
+| Drizzle | `drizzle-kit status` | `generate` → inspect SQL | `drizzle-kit push` | `drizzle-kit status` | `drizzle-kit drop` (prefer backup) |
+| Alembic | `current` + `history` | `upgrade head --sql` | `upgrade head` | `current` (=head) | `downgrade -1` |
+| Django | `showmigrations` | `sqlmigrate <app> <name>` | `migrate` | `showmigrations` ([X]) | `migrate <app> <previous>` |
+| Rails | `db:migrate:status` | read the migration file | `db:migrate` | `db:migrate:status` (up) | `db:rollback STEP=1` |
+| EF Core | `migrations list` | `migrations script` | `database update` | `migrations list` | `database update <previous>` |
+
+Invocation prefix: `npx …` for the Node tools, the project's Python environment for Alembic and Django,
+`dotnet ef …` for EF Core.
+
+## Where a preview does not exist
+
+Sequelize, TypeORM and Rails have no true dry-run. **Treat the migration file itself as the preview** — read
+it out and get it approved before applying. "The tool cannot preview" is not a reason to skip the gate; it is
+a reason the preview is manual.
+
+## Rollback is not a substitute for the backup
+
+Every `Roll back` command above reverses *schema* intent. None of them restores data a destructive migration
+already dropped. That is what the mandatory production backup is for — see `references/backup-restore.md`.
+Drizzle's entry says "prefer backup" for exactly this reason, and the same caution applies to the others
+whenever the migration touched data rather than only structure.

package/kit/skills/dependency-audit/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: dependency-audit
+description: |
+  Dependency risk assessment, read-only: known CVEs, deprecated packages, licence compliance, maintenance
+  status, lockfile integrity, and a justification for every new dependency. Acting on it is dependency-upgrade.
+---
+
+# Dependency Audit
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "dependency audit", "npm audit", "package security", "CVE", "license", "deprecated package", "still maintained", "no longer maintained", "unmaintained", "third party library", "supply chain"
+
+**This skill only reports.** It changes no manifest and no lockfile — bringing dependencies current is
+[[dependency-upgrade]], which classifies each move by risk and verifies the build. Keeping the two apart keeps
+this one safe to run any time, on any branch, including one you are only inspecting.
+
+## Audit axes
+1. **Known vulnerabilities (CVE):** audit appropriate to the ecosystem
+   ```bash
+   npm audit --production           # Node
+   dotnet list package --vulnerable # .NET  (cannot be combined with --deprecated/--outdated)
+   pip-audit                        # Python
+   ```
+2. **License compliance:** flag licenses incompatible with the project such as copyleft/GPL (a risk in commercial closed source).
+3. **Maintenance status:** abandoned / long-unmaintained / single-maintainer packages, and packages the registry
+   itself marks **deprecated** — `dotnet list package --deprecated`, `npm view <pkg> deprecated`. A deprecated
+   package is not a version problem: no bump fixes it, it needs a replacement.
+4. **Transitive dependencies:** also scan vulnerabilities in indirect dependencies.
+5. **Lockfile integrity:** lockfile committed and consistent with the manifest; versions pinned.
+6. **Justification for new dependencies:** is it actually needed? Don't add a heavy package for a single small function (supply-chain surface).
+7. **Install-time execution:** does any dependency run code during installation — `preinstall`/`install`/
+   `postinstall` scripts — and `prepare`, which runs only for a git, link or folder dependency and never for a
+   registry tarball — a build hook, or a setup step that fetches at install time? This is the mechanism the recent
+   registry compromises actually used: the malicious version does not have to be imported, only installed, so a
+   CVE feed and a code review both miss it. Ask two things: which packages declare such a script, and whether
+   the project can install without them at all (`npm ci --ignore-scripts`; for Python the control is refusing source
+   distributions, `pip install --only-binary=:all:`, optionally with `--require-hashes` — a wheel has no install
+   hook, an sdist does; or a vendored, pre-built artefact). A package that cannot install without running code is not disqualified —
+   it is a package whose publisher you are trusting with arbitrary execution on every machine and every runner,
+   which is a decision, not a default.
+8. **Publisher concentration — read it from the registry, not from the repository.** "Many contributors" on a
+   forge says who can open a pull request; it does not say who can publish. The number that matters is who holds
+   the publish right on the registry (`npm owner ls <pkg>` · for PyPI the package JSON's `ownership.roles`,
+   NOT the self-reported `info.maintainer` field · the equivalent ACL for the ecosystem in use) — and whether the
+   PUBLISH PATH itself is challenged, which is not the same as "the account has 2FA": npm's `auth-only` 2FA mode
+   does not gate `npm publish`, and a granular token with bypass-2FA publishes with no second factor, while on
+   PyPI 2FA has been mandatory for every account since 2024 so the real question there is Trusted Publisher
+   versus a long-lived API token. A widely-used
+   package whose registry ACL is one unprotected account is a single compromised credential away from every
+   build that installs it, whatever the contributor graph looks like.
+
+## Output
+Severity-sorted list: `package · version · issue (CVE/license/maintenance) · upgrade path`.
+
+## DoD
+- 0 known HIGH/CRITICAL vulnerabilities; licenses compliant; lockfile consistent; every new package justified.
+- **Every axis resolves to one of three states, and the third is a real answer:** *assessed-clean*,
+  *assessed-flagged*, or *not assessable here — and why*. An axis that was skipped because the tool is missing,
+  the registry was unreachable, or the ecosystem has no equivalent is reported as unassessed, never folded into
+  the clean count. A report that cannot tell "nothing found" from "nobody looked" is the failure this skill
+  exists to prevent, and the sibling `security-scan` already holds the same rule.

package/kit/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dependency-upgrade
+description: |
+  Bring dependencies current without breaking the build: find what is vulnerable, deprecated or behind,
+  classify each target version by risk, apply what is safe, verify, and roll back what is not.
+---
+
+# Dependency Upgrade
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "upgrade dependencies", "outdated packages", "bump versions", "update packages", "keep dependencies current"
+
+## When
+Staying on current versions as an ongoing practice, or reacting to a CVE. [[dependency-audit]] tells you what is
+wrong; this decides what to do about it and does it. It **mutates the manifest and the lockfile**, so it carries
+the same shape as [[db-migration]]: detect the tool, classify by risk, gate the dangerous class behind approval,
+apply, verify, roll back on red.
+
+## 1 — Ask the three separate questions
+They are three different problems with three different answers, and the tooling keeps them separate too.
+
+| Question | Node | .NET | Python |
+|---|---|---|---|
+| What has a **known CVE**? | `npm audit --json` | `dotnet list package --vulnerable` | `pip-audit` |
+| What is **deprecated**? | `npm view <pkg> deprecated` | `dotnet list package --deprecated` | registry / project notes |
+| What is simply **behind**? | `npm outdated --json` | `dotnet list package --outdated` | `pip list --outdated` |
+
+> The three `dotnet list package` flags **cannot be combined** — it is three separate runs, not one.
+
+**Deprecated is not an upgrade.** No version bump fixes it; the package needs a replacement, which is a design
+change with its own review — never fold it into a routine bump.
+
+## 2 — Classify every target version before touching anything
+The risk is not "how old is it", it is "how far does the jump go".
+
+| Class | Rule | Approval |
+|---|---|---|
+| **Security patch** | fixes a known CVE, within the current major | Do it first, on its own commit — it is the one upgrade whose delay has a cost |
+| **Patch** (`x.y.Z`) | bugfix only | Apply, batched |
+| **Minor** (`x.Y.z`) | additive, backward compatible **by promise** | Apply, batched, only if the suite is green afterwards |
+| **Major** (`X.y.z`) | breaking by definition | **Never automatic.** Read the changelog/migration guide, one package per commit, and say what breaks |
+| **Pinned / transitive-only** | pinned deliberately, or not a direct dependency | Leave it. Find out *why* it is pinned before unpinning |
+
+Semver is a promise, not a guarantee: a minor that breaks you is a bug in the package, and your suite is the
+only thing that will tell you. That is why the verify step below is not optional.
+
+## 3 — Apply
+- **Group by class, one commit per group** — a patch batch and a major are not the same change and must not
+  share a commit. A single commit mixing forty bumps is unreviewable and unrevertable.
+- **Preview first.** `npm audit fix --dry-run` before `npm audit fix`. Never reach for `npm audit fix --force`
+  without saying so out loud: it installs **semver-major** upgrades, which is precisely how this task breaks a
+  build while claiming to be a security fix.
+- **The lockfile is part of the change.** Commit it with the manifest; a manifest bump without its lockfile is
+  a change nobody else reproduces ([[dependency-audit]] axis 5).
+- Never hand-edit a lockfile. Let the tool regenerate it.
+
+## 4 — Verify, then decide
+Nothing counts as upgraded until it is observed working — install, build, full test suite, and the project's
+quality gate. Run the app's real entry path if the change touches runtime, not just unit tests ([[testing]]).
+
+- Green → keep it.
+- Red → **roll back this group** (`git checkout -- <manifest> <lockfile>` then reinstall), then either pin, split
+  the batch to find the culprit, or move that package to its own major-upgrade task. Do not "fix forward" a
+  routine bump; that turns maintenance into an unplanned feature.
+- Re-run [[dependency-audit]] afterwards: an upgrade can introduce a new transitive CVE.
+
+## 5 — Continuous, without an autonomous loop
+"Always current" is a **cadence**, not an agent that runs by itself — Crewforth has no timed or self-triggering
+loops, because every mutation here needs an approval a loop cannot give. Continuity comes from somewhere that
+already has a human gate at the end:
+- A scheduled CI job running the step-1 commands and failing on HIGH/CRITICAL ([[ci-pipeline]]).
+- Or a bot (Renovate / Dependabot) opening one PR per group — Crewforth does not reimplement it; the value added
+  is the policy above deciding which PRs merge on green and which need a human to read a changelog.
+- Either way the PR passes through the ordinary gates: build, tests, [[security-scan]], review, approval.
+
+## DoD
+- Vulnerable, deprecated and outdated were asked as three separate questions, with the command output shown.
+- Every applied upgrade is classed patch / minor / major, and no major went in automatically or unexplained.
+- Security fixes landed first and separately.
+- Manifest and lockfile moved together; no lockfile was hand-edited.
+- Build + full suite were observed green after the change, or the group was rolled back and named.
+- Deprecated packages are reported as replacement work, not silently bumped.

package/kit/skills/deploy/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: deploy
+description: |
+  Ship a build reversibly — to a host you manage or a platform that manages it. Pick the topology first, keep
+  the previous version reachable, gate on health, roll back without rebuilding. Use when shipping anywhere
+  users can reach.
+---
+
+# Deploy
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "deploy", "push to the server", "to the server", "onto the server", "build on the server", "install on the VPS", "ship it to the server", "go to production", "to production", "go live"
+
+A deploy has a single idea, and it does not depend on where you are deploying: **make the new version live in a
+way you can undo.** Keep the previous version reachable until the new one has proved itself; if it fails the
+health gate, go back to the old one and nobody notices.
+
+**Two topologies implement that idea differently, and mixing them is where deploys go wrong.** On a host you
+manage, "reversible" means the previous release still sits on disk and the swap is a pointer you can move back.
+On a platform that manages the host for you, "reversible" means the previous *artefact* is still addressable and
+you re-point the environment at it — you do not rebuild it. Phase 0 picks the branch; everything after follows.
+
+> **Crewforth adaptation (local, .claude/):** Any backend runtime (Docker recommended). **Deploy requires explicit
+> approval (§4.4)**; a backup before every swap and a health gate after are mandatory. If `.deploy.yml` carries server
+> credentials it goes into `.gitignore`. §4 Prohibitions apply.
+
+## Phase 0 — Which topology
+Answer before anything else, because the rest of the skill forks here. Ask if it is not obvious; do not infer it
+from the language or the framework.
+
+| | **A · Self-managed host** | **B · Managed platform** |
+|---|---|---|
+| You have | SSH to a machine you own or rent | an API/CLI, and no shell on the box |
+| A release is | a directory on that host | an immutable artefact (image digest, build id, bundle) |
+| "Deploy" means | put the files in place and restart | promote an existing artefact to an environment |
+| Rollback means | move the pointer back to the previous directory | re-point the environment at the previous artefact |
+| Owned by | **`references/topology-a.md`** (phases 1–5) | **`references/topology-b.md`** (phases B1–B4) |
+
+Signals for B: the platform builds from a push, or the runtime is described as containers/functions/dynos/pods
+that you do not administer. Signals for A: you are given a host, a user and a port. A Kubernetes cluster is B
+when a controller reconciles it from a manifest, and A only if you are genuinely hand-placing files on nodes.
+
+**If both are in play** — a managed platform in front, a self-managed worker behind — run the branches
+separately and gate each on its own health check. One approval does not cover two topologies.
+
+## Checklist (A · self-managed host)
+- [ ] Topology decided (Phase 0)
+- [ ] Runtime + deploy method determined
+- [ ] Config taken from `.deploy.yml`/the user, SSH verified
+- [ ] Reverse proxy + (if there is a domain) SSL in place
+- [ ] Running version backed up to `releases/`
+- [ ] User approved the deploy, new version deployed
+- [ ] Health gate passed (otherwise automatic rollback performed)
+- [ ] If requested, single-command scripts (`deploy.sh` / `adopt.sh`) generated
+
+## Checklist (B · managed platform)
+- [ ] Topology decided (Phase 0)
+- [ ] Artefact built once and addressed immutably (digest / build id, not a moving tag)
+- [ ] Which artefact is in which environment is recorded
+- [ ] Config and secrets injected per environment, not baked into the artefact
+- [ ] User approved the promotion to this environment
+- [ ] Health gate passed from OUTSIDE — not the platform's own status
+- [ ] Previous artefact still addressable, and the migration question settled before the deploy
+
+---
+
+## The phases — read ONE branch
+
+Phase 0 picked it; loading both is the mistake this skill opens with.
+
+- **A · self-managed host** → **`references/topology-a.md`**: runtime/method detection, `.deploy.yml` + SSH,
+  reverse proxy and SSL, the backup-then-swap for Docker and bare-metal, the health gate, the rollback.
+- **B · managed platform** → **`references/topology-b.md`**: build once and address it immutably, promote
+  without rebuilding, health-gate from outside the platform, roll back by re-pointing.
+
+The invariant rules at the end of this file hold on both, and they are the half that must not be read from a
+reference file: they are what an approval is checked against.
+
+## Single-command scripts (optional)
+
+After a successful deploy, **ask** whether to generate project-specific `deploy.sh` / `adopt.sh` (single-command
+deploy/update). Derive the steps from the real project (package.json / Dockerfile / Makefile / compose), never a
+generic template. Full guidance + what each script contains: **`references/scripts.md`**.
+
+---
+
+## Invariant rules
+These hold on BOTH branches; where the mechanism differs, the rule does not.
+0. **The topology is decided, not assumed** — Phase 0, once, out loud. Everything downstream depends on it.
+1. **No deploy without approval** — show the method/host/domain/port plan, wait for approval.
+2. **Always back up before the swap** — timestamped into `releases/`; if the backup fails, abort.
+3. **Always a health gate after the swap** — HTTP + process; if it doesn't pass, automatic rollback.
+4. **Keep the last 3 versions** — don't delete them all.
+5. **Don't deploy to prod without knowing the target** — host/deploy_path/domain must be approved.
+6. **Verify SSH first** — if you can't connect, fail fast.
+7. **Don't expose the port directly** — the app binds to `127.0.0.1`, outward only through the proxy.
+8. **SSL is mandatory when there's a domain** — always set it up unless `ssl` is explicitly `false`.
+9. **Never rebuild to roll back** (B) — promote the previous artefact. A rebuild is a different artefact.
+10. **The platform's own status is not the health gate** (B) — verify from where a user stands.
+11. **Rolling back code does not roll back a migration** — settle the schema question before the deploy.

package/kit/skills/deploy/references/proxy-ssl.md

@@ -0,0 +1,56 @@
+# Reverse proxy and SSL — the file contents
+
+Read the half you need. A deploy uses Nginx **or** Caddy, never both, and the two paths differ most exactly
+where it matters: Caddy obtains and renews the certificate itself, Nginx needs Certbot wired up separately.
+
+The decision — which proxy is installed, whether SSL applies at all, and that the app binds only to
+`127.0.0.1` — stays in `SKILL.md`. This file is what to write once that is settled.
+
+## Nginx
+
+Site config:
+
+```nginx
+server {
+  listen 80;
+  server_name DOMAIN;
+  location / {
+    proxy_pass http://127.0.0.1:APP_PORT;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+```
+
+Link it into `sites-enabled` with `ln -s`, then `nginx -t && systemctl reload nginx`. Run `nginx -t` before
+the reload every time — a reload on a broken config takes the site down, and the test costs nothing.
+
+### SSL on the Nginx path
+
+Skip entirely when `ssl: false` or there is no domain. **Never attempt SSL on a bare IP** — a certificate
+authority cannot issue for one, and the attempt burns rate-limited quota on the domain you will use later.
+
+Verify DNS resolves to this host *first*, or Certbot's challenge fails in a way that looks like a proxy fault:
+
+```bash
+dig +short $DOMAIN        # must equal $HOST
+certbot --nginx -d $DOMAIN --non-interactive --agree-tos -m admin@$DOMAIN
+systemctl enable certbot.timer   # automatic renewal — without this the site breaks in 90 days
+```
+
+## Caddy
+
+```
+DOMAIN {
+  reverse_proxy 127.0.0.1:APP_PORT
+}
+```
+
+`systemctl reload caddy`. Caddy handles the certificate and its renewal on its own — no Certbot, no timer, no
+separate SSL step. If the domain does not yet resolve, Caddy will retry rather than fail loudly, so check
+`journalctl -u caddy` when a fresh domain serves plain HTTP longer than expected.

package/kit/skills/deploy/references/rollback.md

@@ -0,0 +1,18 @@
+# Phase 5 — Rollback (run on health-gate failure)
+
+Undo the swap: put the most recent version in `releases/` back into `current`, restart the service, repeat the
+health gate (Phase 4).
+```bash
+LATEST=$(ssh -i $SSH_KEY $USER@$HOST "ls -dt $DEPLOY_PATH/releases/*/ 2>/dev/null | head -1")
+[ -z "$LATEST" ] && { echo "ERROR: no backup — rollback impossible"; exit 1; }
+ssh -i $SSH_KEY $USER@$HOST "
+  mkdir -p $DEPLOY_PATH/current
+  rsync -a --delete ${LATEST%/}/ $DEPLOY_PATH/current/   # atomic swap — no 'rm -rf' (guard-safe)
+  { docker rm -f $APP 2>/dev/null && docker run -d --name $APP --restart unless-stopped \
+      -p 127.0.0.1:$APP_PORT:$APP_PORT $APP:previous; } \
+    || systemctl restart $APP || pm2 restart $APP
+"
+```
+> **Note:** Rollback uses `rsync --delete` instead of `rm -rf` so `guard-bash` (the local `rm -rf` block) doesn't
+> block the automatic rollback. The deploy verbs (`ssh`/`rsync`/`docker`) pass through the approval gate via
+> `settings.json` `permissions.ask` — they run with approval, not silently.

package/kit/skills/deploy/references/scripts.md

@@ -0,0 +1,9 @@
+# Single-command scripts (optional)
+
+After a successful deploy, **ask:** "Shall I generate `deploy.sh` and `adopt.sh` so you can deploy/update with a single command in the future?"
+
+If you generate them, **don't use a generic template** — analyze the actual project (package.json scripts / Dockerfile / Makefile / docker-compose / `.env.example`) and derive the exact build+start steps. Two scripts:
+- **`deploy.sh`** — first-time setup + deploy: load config · verify SSH · proxy + SSL · back up to `releases/` · project-specific build · transfer · dependencies · start · health gate with retries · rollback on failure.
+- **`adopt.sh`** — quick update: config · backup · code sync · (if needed) build/dependencies · restart · health gate · rollback on failure.
+
+Rules: `chmod +x`; if `.deploy.yml` carries credentials, ask about `.gitignore`; don't overwrite an existing script without approval (show a diff); no hardcoded credentials — always read from `.deploy.yml`; comment and explain every project-specific decision.

package/kit/skills/deploy/references/topology-a.md

@@ -0,0 +1,128 @@
+# Topology A — self-managed host (phases 1-5)
+
+Read this only when Phase 0 answered **A**: you have SSH to a machine you own or rent, a release is a directory on
+that host, and rollback means moving a pointer back. On topology B read `references/topology-b.md` instead — never
+both, because mixing them is where deploys go wrong.
+
+The invariant rules in SKILL.md hold over everything here: no deploy without approval, back up before the swap,
+health-gate after it, keep the last three versions, the app binds to `127.0.0.1` only.
+
+## Phase 1 (A) — Surface: method and runtime
+
+```bash
+if   [ -f Dockerfile ] || [ -f docker-compose.yml ]; then METHOD=docker
+elif [ -f package.json ];                                then METHOD=bare RUNTIME=node
+elif [ -f requirements.txt ] || [ -f pyproject.toml ];   then METHOD=bare RUNTIME=python
+elif [ -f go.mod ];                                      then METHOD=bare RUNTIME=go
+elif ls ./*.csproj ./*.sln >/dev/null 2>&1;              then METHOD=bare RUNTIME=dotnet
+elif [ -f pom.xml ] || [ -f build.gradle ];              then METHOD=bare RUNTIME=java
+elif [ -f Cargo.toml ];                                  then METHOD=bare RUNTIME=rust
+elif [ -f Gemfile ];                                     then METHOD=bare RUNTIME=ruby
+elif [ -f composer.json ];                               then METHOD=bare RUNTIME=php
+else METHOD=unknown; fi
+```
+If `method: docker` and there's no Dockerfile, generate one. `method: bare` → a process manager suited to the runtime; build the release artefact with the runtime's own command (`dotnet publish -c Release`, `mvn package`, `cargo build --release`, …) and run it under systemd. Prefer Docker for any runtime whose bare setup needs a toolchain on the box. If detection is ambiguous, ask the user — never guess a runtime.
+
+---
+
+## Phase 2 (A) — Preparation: config, SSH, proxy, SSL
+
+**Config** — read `.deploy.yml` from the root, and if it's missing ask for each field:
+```yaml
+host: 192.168.1.100        # VPS IP/hostname (required)
+user: deploy               # SSH user (required)
+ssh_key: ~/.ssh/id_rsa     # private key
+app_port: 3000             # application port (required)
+health_check: /api/health  # HTTP path (default /)
+deploy_path: /var/www/app  # server path (required)
+method: auto               # auto | docker | bare
+domain: app.example.com    # for proxy/SSL (optional)
+ssl: true                  # default true if there is a domain
+reverse_proxy: auto        # auto | nginx | caddy
+```
+**Verify SSH first** — if you can't connect, stop immediately:
+```bash
+ssh -i $SSH_KEY -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new $USER@$HOST "echo OK"
+```
+
+**Reverse proxy** — detect the one installed on the server (`auto` → Caddy if present, otherwise Nginx). The application binds only to `127.0.0.1`; it is exposed outward **only** through the proxy.
+
+**SSL** — skip if `ssl: false` or there's no domain, and never on a bare IP. On the Nginx path, verify DNS resolves to the host (`dig +short $DOMAIN` = `$HOST`) *before* running Certbot; on the Caddy path the certificate and its renewal are automatic and there is no separate step.
+
+Config file contents for both proxies, the Certbot commands and the renewal timer: **`references/proxy-ssl.md`** — read the half for the proxy you found, not both.
+
+---
+
+## Phase 3 (A) — Swap: keep the old, put the new
+
+**First back up the running version** (timestamped `releases/`, last 3 kept):
+```bash
+ssh -i $SSH_KEY $USER@$HOST "
+  mkdir -p $DEPLOY_PATH/releases
+  [ -d $DEPLOY_PATH/current ] && cp -a $DEPLOY_PATH/current $DEPLOY_PATH/releases/$(date +%Y%m%d_%H%M%S)
+  cd $DEPLOY_PATH/releases && ls -dt */ | tail -n +4 | xargs -r rm -rf
+"
+```
+
+**Docker** — build the image locally, transfer it, replace the container:
+```bash
+docker build -t $APP:latest .
+docker save $APP:latest | gzip | ssh -i $SSH_KEY $USER@$HOST "gunzip | docker load"
+ssh -i $SSH_KEY $USER@$HOST "
+  docker rm -f $APP 2>/dev/null || true
+  docker run -d --name $APP --restart unless-stopped -p 127.0.0.1:$APP_PORT:$APP_PORT $APP:latest
+"
+```
+
+**Bare-metal** — `rsync` the source, install dependencies, start with the process manager:
+```bash
+rsync -avz --delete --exclude .git --exclude node_modules --exclude .venv \
+  -e "ssh -i $SSH_KEY" ./ $USER@$HOST:$DEPLOY_PATH/current/
+```
+
+| Runtime | Dependencies + startup |
+|---|---|
+| Node | `npm ci --production` → PM2: `pm2 start ecosystem.config.js --name $APP || pm2 start npm --name $APP -- start` → `pm2 save` |
+| Python | `python3 -m venv venv && venv/bin/pip install -r requirements.txt` → systemd (gunicorn/uvicorn or `python main.py`) |
+| Go | build locally `GOOS=linux GOARCH=amd64 go build -o $APP` → `scp` → systemd |
+
+systemd unit (for Python/Go, fill in ExecStart per the runtime):
+```ini
+[Unit]
+After=network.target
+[Service]
+Type=simple
+User=$USER
+WorkingDirectory=$DEPLOY_PATH/current
+ExecStart=<runtime command>
+Restart=always
+Environment=PORT=$APP_PORT
+[Install]
+WantedBy=multi-user.target
+```
+`systemctl daemon-reload && systemctl enable --now $APP`.
+
+---
+
+## Phase 4 (A) — Health gate
+
+Right after the swap; retry for ~30 s until a 200 comes back. **If it doesn't pass, trigger Phase 5 automatically.**
+```bash
+ssh -i $SSH_KEY $USER@$HOST '
+  for i in $(seq 1 6); do
+    [ "$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:'"$APP_PORT$HEALTH_CHECK"')" = 200 ] \
+      && { echo "Health gate PASSED"; exit 0; }
+    sleep 5
+  done
+  echo "Health gate FAILED"; exit 1
+'
+```
+Also verify the process is up: `docker ps` on Docker, otherwise `systemctl is-active $APP` / `pm2 show $APP`.
+
+---
+
+## Phase 5 (A) — Rollback
+
+On health-gate failure: put the most recent `releases/` version back into `current`, restart the service, and
+re-run the health gate (Phase 4). Guard-safe rollback script (uses `rsync --delete`, not `rm -rf`) + the
+approval-gate note: **`references/rollback.md`**.

package/kit/skills/deploy/references/topology-b.md

@@ -0,0 +1,44 @@
+# Topology B — managed platform (phases B1-B4)
+
+Read this only when Phase 0 answered **B**: you have an API/CLI and no shell on the box, a release is an immutable
+artefact, and rollback means re-pointing the environment at the previous one. On topology A read
+`references/topology-a.md` instead — never both.
+
+The invariant rules in SKILL.md hold over everything here, including the two that are B's alone: never rebuild to
+roll back, and the platform's own status is not the health gate.
+
+## Phase B1 — Build once, and know what you built
+The artefact is produced **once**, and the same one moves through every environment. Rebuilding for production
+means the thing you tested is not the thing you shipped — the inputs moved underneath you (a floating base
+image, a lockfile resolved a minute later, a different builder). Two consequences:
+- **Address it immutably.** A digest or a build id, never a moving tag. `latest`, `main` and a branch name all
+  name different bytes on different days, which makes both promotion and rollback unverifiable.
+- **Record which artefact is in which environment.** If nobody can answer "what exactly is running in
+  production", rollback is a guess and the health gate has nothing to compare against.
+
+## Phase B2 — Promote, do not rebuild
+Deploying to the next environment means pointing that environment at an artefact that already exists and has
+already passed the previous gate. Configuration is injected per environment, never baked into the artefact — the
+same bytes must be able to run in staging and in production, or you are back to rebuilding. Secrets come from
+the platform's own store; a secret inside the artefact ships to everyone who can pull it.
+
+**Approval is per environment (§4.4), and per topology.** Promoting to a user-facing environment is a deploy,
+whatever the platform calls it.
+
+## Phase B3 — Health gate, from outside
+Identical in spirit to Phase 4 (A) and worth stating because platforms invite the opposite: **the platform
+reporting "deployed", "healthy" or "active" is not the verification.** It reports that its own reconciliation
+finished. Check the thing users touch — a request through the public entry point, a real response body, the
+version endpoint returning the version you promoted. Give it the same failure rule: if the gate does not pass,
+go back before investigating.
+
+## Phase B4 — Roll back by re-pointing
+Rollback is promoting the previous artefact, not rebuilding the previous commit — a rebuild is a new artefact
+with new inputs and it may not even reproduce the bug you are escaping. So:
+- Keep the previous artefacts addressable for at least as long as you promise to be able to roll back. A
+  retention policy that deletes them is a rollback policy that does not work.
+- Rolling back **code** does not roll back a **migration**. If the release included an irreversible schema
+  change, the old artefact may not run against the new schema — that is `db-migration`'s expand/contract
+  question and it has to be answered before the deploy, not during the incident.
+- After a rollback, the environment is running an artefact older than the recorded state. Say so plainly to
+  whoever is watching; a silent rollback is how two people fix the same outage twice.

package/kit/skills/docs-writer/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: docs-writer
+description: |
+  Keeps documentation in sync with the code: README, usage and related docs when a public API or behavior
+  changes. Leaves no dead or misleading docs behind.
+---
+
+# Documentation
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "documentation", "docs", "update README", "API docs", "write docs", "document it", "write usage"
+
+Goal: the docs must **match the code**. Wrong/stale docs are worse than no docs (they inspire trust and mislead).
+Trigger: when a public API, command, configuration, or user-visible behavior changes.
+
+## When it is mandatory
+- A public function/endpoint/CLI signature or behavior changed.
+- A new feature, configuration key, or environment variable was added.
+- The install/run steps changed.
+- A breaking change was made (also coordinate via `release`/CHANGELOG).
+
+## Checklist
+- [ ] Docs are up to date for the changed public surface
+- [ ] Examples **work** (copy-paste tested / mentally traced)
+- [ ] Dead/misleading wording removed (no leftover old name/parameter)
+- [ ] New configuration/env documented (default + whether required)
+- [ ] Scope minimal — not a repetition of the code, but "why/how to use it"
+- [ ] No secret/real credential in the docs (use a placeholder)
+
+## How
+1. **Identify the changed surface** — extract the public signature/behavior diff from the diff.
+2. **Find the right doc** — README, `docs/`, docstring, OpenAPI, command `--help`. If there is more than one, update them all.
+3. **Write**: what it does · how it is called (example) · input/output · limits/error cases. Short and correct.
+4. **Verify the examples** — does the command/code example actually run.
+5. **Clean up the old** — delete references to removed APIs/parameters.
+6. **Translation**: if the user-visible doc is multilingual, coordinate with `i18n-integrity`.
+
+## Principles
+- **Single source** — behavior lives in the code; the doc *explains* it, does not copy it (a copied doc goes stale).
+- **Example > paragraph** — a working example beats three paragraphs.
+- **Minimal** — don't write a giant doc no one will maintain; answer the most-asked question.
+
+## Co-authoring a longer doc (guide, tutorial, README rewrite)
+For a substantial doc the content lives in the author's head, not the diff — don't guess it. Interview for intent
+and audience, draft in passes, and let the user steer before you polish. The collaborative workflow (audience/intent
+questions, outline-first, section-by-section drafting, revision loop): **`references/coauthoring.md`**.
+
+## Invariant rules
+1. **Correctness > completeness** — don't write a wrong doc; if unsure, flag it/ask.
+2. **Examples must work.**
+3. **Leave no stale/dead docs.**
+4. **No secret/real credential** — use a placeholder (aligned with §4).
+5. **Don't repeat the code** — don't just copy the signature; explain the usage.

package/kit/skills/docs-writer/references/coauthoring.md

@@ -0,0 +1,34 @@
+# Co-authoring a longer doc
+
+Loaded on demand. For a substantial doc (a guide, tutorial, concept explainer, README rewrite) — not a mechanical
+sync of a changed signature. Here the content lives in the author's head; your job is to draw it out and shape it,
+not to invent it.
+
+## Why not just write it
+
+A generated long-form doc that no one steered reads as generic, states things the maintainer wouldn't, and quietly
+guesses at intent — then it has to be rewritten anyway. Co-authoring front-loads the cheap questions so the expensive
+draft is right the first time.
+
+## The workflow
+
+1. **Interview first (before drafting).** Ask, don't assume:
+   - **Audience** — who reads this? (new user, integrator, contributor, ops) Their assumed knowledge sets the level.
+   - **Intent** — what should the reader be able to *do* after? One doc, one job.
+   - **Scope** — what's explicitly out of scope? (prevents the doc sprawling)
+   - **Voice/constraints** — house style, terminology, things that must/mustn't be said.
+   Keep it to the few questions whose answers actually change the draft — offer options where useful, don't interrogate.
+
+2. **Outline, get sign-off.** Propose the section structure (headings + one line each) and confirm it *before* writing prose. Re-structuring an outline is cheap; re-structuring 800 words is not.
+
+3. **Draft in passes, not one wall.** Write section by section (or a first full pass explicitly marked as a draft). Surface the open questions inline (`> TODO: confirm default value`) rather than silently guessing — the maintainer fills the gaps you can't.
+
+4. **Revision loop.** Invite specific feedback ("is the auth section at the right level?"), apply it, and keep the diff reviewable. Don't rewrite wholesale on each round — converge.
+
+5. **Then apply the base discipline.** Once the content is agreed, the SKILL.md rules take over: examples must actually run, no stale/dead wording, no real secrets, single-source (explain the code, don't copy it), and coordinate `i18n-integrity` if it's multilingual.
+
+## Keep it honest
+
+- Don't state capabilities, defaults, or roadmap you haven't verified — ask or mark as TODO.
+- Don't pad to look thorough; the maintainer maintains every sentence you add.
+- The author's voice wins over yours — you're drafting *their* doc, not authoring your own.