@taskless/cli 0.11.0 → 0.11.2

package/dist/recipes-tkku5bYo.js

@@ -0,0 +1,2994 @@
+import { o as f, a as m, s as i, l as j, _ as F, t as $ } from "./schemas-OhdGAhu_.js";
+const ze = "npx @taskless/cli";
+function Ye() {
+  return "npx @taskless/cli";
+}
+const z = "%(TASKLESS_CLI)s";
+function He(e) {
+  return e.replaceAll(z, "npx @taskless/cli");
+}
+function Be(e) {
+  return e;
+}
+function Xe(e) {
+  return e;
+}
+const Y = `# Topic: auth     (CLI v%(CLI_VERSION)s / topic v1)
+
+## Goal
+Manage Taskless authentication. Three branches:
+- **Login**: start the device-code flow and wait for the user to
+  approve in their browser.
+- **Logout**: remove the saved token.
+- **Status**: check whether a token is present and whose identity
+  it represents.
+
+## Preconditions
+- \`.taskless/\` directory exists.
+- For login: the user has a browser to approve the device code.
+
+## Steps
+
+Pick the branch matching the user's intent.
+
+### Login
+
+1. Run:
+   \`\`\`
+   %(TASKLESS_CLI)s auth login
+   \`\`\`
+2. The CLI prints a URL and a device code. Tell the user to open the
+   URL and enter the code.
+3. The CLI polls until the token is approved. On success, the token
+   is written to \`.taskless/.env.local.json\` and a confirmation is
+   printed.
+4. Report success. Suggest \`%(TASKLESS_CLI)s info\` to verify identity.
+
+The \`--anonymous\` flag is rejected on \`auth login\`, it errors with
+"auth commands cannot be anonymous". Don't pass it.
+
+### Logout
+
+1. Run:
+   \`\`\`
+   %(TASKLESS_CLI)s auth logout
+   \`\`\`
+2. The CLI removes the saved token (or reports "Not logged in" if
+   none was present).
+3. Report the outcome.
+
+### Status (no subcommand)
+
+1. Run:
+   \`\`\`
+   %(TASKLESS_CLI)s auth
+   \`\`\`
+2. Output is one of:
+   - "Not logged in." (with hint to run \`auth login\`)
+   - "Logged in as <user> (<orgs>)."
+   - "Logged in, but unable to verify identity." (token expired or
+     revoked, suggest re-login)
+3. Report to the user.
+
+## Errors
+
+\`auth login\` and \`auth logout\` accept \`--json\`. On error, the
+standardized \`{ ok: false, code, message }\` envelope is written to
+stdout (and human text on stderr is suppressed). On success in
+\`--json\` mode, the commands exit 0 silently, no success envelope is
+emitted. The status path (\`%(TASKLESS_CLI)s auth\` with no subcommand) accepts
+\`--json\` for forward-compat but currently has no error paths to
+report.
+
+| code            | meaning                                                                              | fix                                  |
+|-----------------|--------------------------------------------------------------------------------------|--------------------------------------|
+| \`INVALID_INPUT\` | \`--anonymous\` passed to \`auth login\` (rejected: auth commands cannot be anonymous)   | Don't pass \`--anonymous\`             |
+| \`NETWORK_ERROR\` | Device flow / token endpoint unreachable, or the device code expired before approval | Check connectivity; retry            |
+| \`AUTH_REQUIRED\` | The user denied the authorization request in their browser                           | Re-run \`%(TASKLESS_CLI)s auth login\` |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent info\`: see auth state and skill versions
+- \`%(TASKLESS_CLI)s agent route\`: first action that requires auth
+`, H = `# Topic: check     (CLI v%(CLI_VERSION)s / topic v2)
+
+## Goal
+Run the applicable rules against the codebase and report matches. Two
+rule kinds run: **static** ast-grep rules in \`.taskless/rules/sg/\`, and
+**runtime** rules in \`.taskless/rules/runtime/\` (a directory of ast-grep
+capture rules plus a \`check.ts\`). Used standalone (full project scan),
+in CI (diff-only scan), or after rule create/improve to validate.
+
+## Preconditions
+- \`.taskless/\` directory exists.
+- At least one rule exists in \`.taskless/rules/sg/\` or
+  \`.taskless/rules/runtime/\`. (If none exist, the CLI exits 0 with a
+  friendly message suggesting \`%(TASKLESS_CLI)s rule create\`.)
+- No auth required. Static rules always run; whether runtime rules run
+  depends on auth state. See "What runs".
+
+## What runs
+
+\`check\` never requires auth. The two rule kinds run differently:
+
+- **Static rules** (\`.taskless/rules/sg/<id>/<id>.yml\`) are inert ast-grep patterns
+  and **always run**, in every mode, with no network call. The offline
+  linter posture.
+- **Runtime rules** (\`.taskless/rules/runtime/<name>/\`) execute a
+  \`check.ts\` (arbitrary code), so they run ONLY when that code is
+  verified:
+  - **Logged in** (token or API key): each rule's \`check.ts\` is
+    reconciled against the Taskless service; rules the server blessed
+    (\`run\`) execute, and the rest are withheld and reported (advisory).
+  - **Logged out, \`--anonymous\`, no GitHub remote, or service
+    unavailable**, runtime rules are **skipped** (reported, never run).
+    Static rules still run.
+  - **\`--dangerously-run-scripts\`**: runs every runtime rule trusting
+    local signatures, with no network call, behind a prominent warning.
+    This is the only way to run runtime rules unverified.
+
+Notices about skipped/withheld runtime rules are human-readable stderr
+only: they never change the exit code. Under \`--json\` they do NOT appear
+as warnings; instead an additive optional \`skipped: [{ rule, reason }]\`
+array is included alongside the unchanged \`{ success, results }\`. The
+authoritative allow-list is the server's; the CI backstop
+(\`%(TASKLESS_CLI)s agent ci\`) is the enforcement point for runtime rules.
+
+## Flags
+- \`--json\`: machine output (\`{ success, results, skipped? }\`).
+- \`--anonymous\`: run only static rules; skip runtime rules.
+- \`--dangerously-run-scripts\`: run runtime \`check.ts\` unverified.
+- \`--timeout <seconds>\`: per-runtime-check wall-clock bound (default 10).
+
+## Steps
+
+1. **Decide scope.** Default is a full project scan. If the user
+   specified files (or you're in a CI context with a known diff),
+   pass them as positional arguments.
+
+2. **Invoke the CLI.** Either:
+   \`\`\`
+   %(TASKLESS_CLI)s check --json
+   \`\`\`
+   or, scoped to specific paths:
+   \`\`\`
+   %(TASKLESS_CLI)s check --json src/foo.ts src/bar.ts
+   \`\`\`
+   or, against a git diff:
+   \`\`\`
+   %(TASKLESS_CLI)s check --json $(git diff --name-only main...HEAD)
+   \`\`\`
+   Paths that don't exist on disk are silently filtered, so you can
+   pipe raw \`git diff\` output directly without pre-filtering.
+
+   When runtime rules were present but not run (e.g. logged out), the
+   JSON also carries \`"skipped": [{ "rule": "<name>", "reason": "…" }]\`
+   alongside \`success\`/\`results\`. Surface it so CI can tell that runtime
+   rules did not execute; it never affects the exit code.
+
+3. **Parse the JSON output.** Shape:
+   \`\`\`json
+   {
+     "success": false,
+     "results": [
+       {
+         "source": "ast-grep",
+         "ruleId": "no-eval",
+         "severity": "error",
+         "message": "Avoid eval()",
+         "note": null,
+         "file": "src/foo.ts",
+         "range": {
+           "start": { "line": 12, "column": 4 },
+           "end":   { "line": 12, "column": 14 }
+         },
+         "matchedText": "eval(input)",
+         "fix": null
+       }
+     ]
+   }
+   \`\`\`
+
+4. **Report findings to the user.** Group by \`file\`. Show \`severity\`,
+   \`message\`, and \`ruleId\` for each finding; the \`range.start\` is the
+   useful line/column to surface. The \`success\` field reflects only
+   error-severity findings: \`success: false\` means at least one
+   \`severity: "error"\` finding exists (exit code 1); \`success: true\`
+   with a non-empty \`results\` array means there are only
+   warning/info/hint findings (exit code 0); \`success: true\` with an
+   empty \`results\` array means the codebase is clean. Findings are
+   never reported via the \`{ ok: false, code, message }\` envelope:
+   the envelope only appears when the scan itself fails (e.g.
+   \`SCAN_FAILED\`) and the normal results payload is absent.
+
+## Exit codes
+
+- \`0\`: All checks passed, no rules configured, or all supplied
+  paths missing
+- \`1\`: Errors detected or scan failed
+
+## Errors
+
+When \`--json\` is set, failures emit \`{ ok: false, code, message }\`:
+
+| code          | meaning               | fix                              |
+|---------------|-----------------------|----------------------------------|
+| \`SCAN_FAILED\` | ast-grep scan errored | Report; check rule YAML validity |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: add a rule if none exist
+- \`%(TASKLESS_CLI)s agent ci\`: wire \`check\` into a CI pipeline
+`, B = `# Topic: ci     (CLI v%(CLI_VERSION)s / topic v1)
+
+## Goal
+Wire \`%(TASKLESS_CLI)s check\` into the user's existing CI so rules run
+automatically on pushes and pull requests. Integrate with what they
+already have, never replace or edit their main pipeline.
+
+This recipe teaches two patterns (full scan and diff scan) that
+translate to any CI system. Common systems are listed as hints; if
+you recognize one not on the list, apply the same patterns.
+
+## Preconditions
+- \`.taskless/\` directory exists and contains at least one rule. (If
+  no rules exist, instruct the user to fetch
+  \`%(TASKLESS_CLI)s agent route\` first, wiring CI with zero rules
+  produces an always-green check that gives false confidence.)
+- A local \`%(TASKLESS_CLI)s check\` succeeds (or fails with real findings the
+  user is OK with seeing in CI's first run).
+- No auth required for CI: \`check\` is unauthenticated by default.
+  (Optionally tokenized as a server-enforced backstop; see step 7.)
+
+## Steps
+
+### 1. Discover the user's CI system
+
+Scan the repo root for CI config files. Hints (not exhaustive):
+
+| File / directory          | CI system           |
+|---------------------------|---------------------|
+| \`.github/workflows/*.yml\` | GitHub Actions      |
+| \`.gitlab-ci.yml\`          | GitLab CI           |
+| \`.circleci/config.yml\`    | CircleCI            |
+| \`Jenkinsfile\`             | Jenkins             |
+| \`azure-pipelines.yml\`     | Azure Pipelines     |
+| \`bitbucket-pipelines.yml\` | Bitbucket Pipelines |
+| \`.buildkite/\`             | Buildkite           |
+| \`.drone.yml\`              | Drone               |
+| \`.travis.yml\`             | Travis CI           |
+
+Sum up what you found and confirm with the user. If zero match, ask
+which CI they use. If multiple match, ask which should run Taskless.
+
+### 2. Agree on the scan pattern
+
+- **Full scan**: \`%(TASKLESS_CLI)s check\`. Scans everything. Best for runs
+  on the main/default branch.
+- **Diff scan**: \`%(TASKLESS_CLI)s check $(git diff --name-only ...)\`.
+  Faster for PR builds. Per-CI diff target var:
+
+| CI                  | Target branch variable                        |
+|---------------------|-----------------------------------------------|
+| GitHub Actions      | \`github.base_ref\`                             |
+| GitLab CI           | \`CI_MERGE_REQUEST_TARGET_BRANCH_NAME\`         |
+| CircleCI            | \`CIRCLE_BRANCH\` (fetch main and diff against) |
+| Jenkins             | \`env.CHANGE_TARGET\`                           |
+| Azure Pipelines     | \`System.PullRequest.TargetBranch\`             |
+| Bitbucket Pipelines | \`BITBUCKET_PR_DESTINATION_BRANCH\`             |
+
+  \`%(TASKLESS_CLI)s check\` silently filters paths that don't exist, so raw
+  \`git diff --name-only\` output can pipe in directly.
+
+**Recommended default:** diff scan on PRs, full scan on pushes to
+main.
+
+### 3. Verify locally first
+
+Run \`%(TASKLESS_CLI)s check\`:
+- Clean pass → proceed.
+- "No rules configured" → stop. Fetch \`%(TASKLESS_CLI)s agent route\`.
+- Findings → tell the user CI will fail; ask whether to fix,
+  suppress, or proceed knowing the first CI run will be red.
+
+### 4. Generate the config
+
+Rules:
+1. Write a NEW standalone file. Never modify the user's existing
+   CI config.
+2. Prefer the CI's native include mechanism. Tell the user the one
+   line they need to add to their main config.
+3. If the file you'd write already exists, ask before overwriting.
+
+Canonical paths:
+
+| CI                  | File path                                                           |
+|---------------------|---------------------------------------------------------------------|
+| GitHub Actions      | \`.github/workflows/taskless.yml\` (standalone, no include needed)    |
+| GitLab CI           | \`.taskless/ci/gitlab.yml\` (user adds \`include\`)                     |
+| CircleCI            | \`.taskless/ci/circleci-job.yml\` (no include, user copies job)      |
+| Jenkins             | \`.taskless/ci/taskless.Jenkinsfile\` (user \`load()\`s)                |
+| Azure Pipelines     | \`.taskless/ci/azure-taskless.yml\` (user references via \`template:\`) |
+| Bitbucket Pipelines | \`.taskless/ci/bitbucket-pipelines.yml\` (user merges manually)       |
+| Other               | \`.taskless/ci/<system>.<ext>\` + clear wiring instructions           |
+
+### 5. GitHub Actions reference template
+
+The reference template, translate the same shape (checkout with
+full history, set up Node, conditional check) for other CIs.
+
+Substitute \`%(PACKAGE_MANAGER_DLX)s\` with the CI runner's own complete
+invocation, \`npx @taskless/cli\`, \`pnpm dlx @taskless/cli\`,
+\`yarn dlx @taskless/cli\`, or \`bunx @taskless/cli\`, picking the launcher
+from \`pnpm-lock.yaml\`/\`yarn.lock\`/\`bun.lockb\`. It is a whole command on
+its own, exactly as the template uses it; never combine it with
+\`%(TASKLESS_CLI)s\`. Which launcher the repository you are wiring up should
+run is a different question from how this recipe was fetched, which is why
+it stays a separate placeholder.
+
+\`\`\`yaml
+name: Taskless
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Taskless check
+        run: |
+          if [ "\${{ github.event_name }}" = "pull_request" ]; then
+            git fetch origin "\${{ github.base_ref }}" --depth=1
+            FILES=$(git diff --name-only "origin/\${{ github.base_ref }}...HEAD")
+            if [ -z "$FILES" ]; then
+              echo "No changed files."
+              exit 0
+            fi
+            %(PACKAGE_MANAGER_DLX)s check $FILES
+          else
+            %(PACKAGE_MANAGER_DLX)s check
+          fi
+\`\`\`
+
+Simplifications:
+- Full-scan only → drop the \`if\`, just run \`%(PACKAGE_MANAGER_DLX)s check\`.
+- Diff-scan only → remove the \`push:\` trigger.
+
+### 6. Translate to other CIs
+
+The six universal steps:
+1. Set up Node (v20 default; match the user's existing CI version).
+2. Fetch with full depth (or enough to reach the target branch).
+3. Fetch the target branch.
+4. Compute changed files with \`git diff --name-only "origin/<target>...HEAD"\`.
+5. Exit early if the diff is empty.
+6. Call \`%(PACKAGE_MANAGER_DLX)s check $FILES\` for PR builds, or
+   \`%(PACKAGE_MANAGER_DLX)s check\` for main-branch builds.
+
+YAML for GitHub/GitLab/Azure/Bitbucket; Groovy for Jenkins;
+different structure for CircleCI. The six steps stay the same.
+
+### 7. Authentication in CI (optional backstop)
+
+\`%(TASKLESS_CLI)s check\` does NOT require authentication. The generated CI
+config works out of the box with no secrets and scans all local rules.
+
+Static ast-grep rules always run in CI with no secrets. **Runtime
+rules** (\`.taskless/rules/runtime/\`, which execute a \`check.ts\`) only
+run when their code is server-verified, so an unauthenticated CI job
+runs the static rules and skips the runtime ones.
+
+Exposing a \`TASKLESS_TOKEN\` secret turns CI into the **backstop** for
+runtime rules: an authenticated \`check\` reconciles each runtime rule's
+\`check.ts\` against the Taskless service and runs exactly the
+server-blessed set, withholding any that drift or were never issued.
+This is the enforcement point for runtime rules, local developer runs
+skip them unless \`--dangerously-run-scripts\` is passed. To wire it, set
+the token as an env var on the check step (GitHub Actions):
+
+\`\`\`yaml
+      - name: Taskless check
+        env:
+          TASKLESS_TOKEN: \${{ secrets.TASKLESS_TOKEN }}
+        run: |
+          ...
+\`\`\`
+
+Add this only when the user wants server-enforced rules in CI; the
+unauthenticated default remains fully supported. Also mention auth if
+the user explicitly asks to run authenticated commands (e.g.
+\`rule create\`/\`rule improve\`) in CI, uncommon.
+
+### 8. Package manager caveats
+
+- **pnpm**: \`pnpm dlx\` works but has slow cold starts. If the user's
+  pipeline already sets up pnpm, suggest adding \`@taskless/cli\` as a
+  dev dep and calling it via \`pnpm taskless check\`. That \`taskless\` is the
+  binary pnpm resolves from the wired repo's own \`node_modules/.bin\`, not
+  this CLI's invocation, so it is not \`%(TASKLESS_CLI)s\`.
+- **Yarn v1 (classic)**: doesn't support \`yarn dlx\`. Use \`npx\`.
+- **Bun**: \`bunx\` works.
+
+### 9. Report back
+
+Show:
+1. The path written and a 10-15 line excerpt.
+2. For CIs needing manual wiring, the exact \`include:\` / reference
+   line for their main config.
+3. \`git status\` so they can review before committing.
+4. A note that the first CI run exercises rules, if existing
+   matches exist, CI will fail until fixed or suppressed.
+
+## Errors
+
+- **No rules** → fetch \`%(TASKLESS_CLI)s agent route\`. Don't write CI
+  config.
+- **Unrecognized CI** → produce a generic \`.taskless/ci/check.sh\`
+  script implementing the six universal steps. Be upfront it's a
+  starting point.
+- **Target CI file exists, user declines overwrite** → stop. Show
+  what you would have written; let them reconcile manually.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent check\`: the command being wired into CI
+- \`%(TASKLESS_CLI)s agent route\`: required if no rules exist yet
+`, X = `# Topic: create-legacy-rule     (CLI v%(CLI_VERSION)s / topic v1)
+
+## You are here
+This is \`create-legacy-rule\`. It helps you write a rule for a linter the
+repository already runs (ESLint, Ruff, RuboCop, Stylelint) in that
+tool's own dialect, so that tool enforces it.
+If that is not the kind of check you need, re-run \`%(TASKLESS_CLI)s agent route\`
+and follow its decision rather than adapting this recipe.
+
+## Goal
+Author a rule in a linter the repository ALREADY uses, expressed in that
+tool's own dialect (an ESLint rule, a Ruff rule selection, a RuboCop cop,
+a Stylelint rule, etc.). Taskless does not maintain a catalog of linter
+rules, you source the knowledge from the repo first and the web second,
+then write the rule where that tool expects it.
+
+## Preconditions
+- The repo has a detected linter (confirm via \`%(TASKLESS_CLI)s detect --json\`).
+- The agent can read/write files and fetch web pages.
+- No auth required.
+
+## Steps
+
+1. **Confirm the target tool.** Use \`%(TASKLESS_CLI)s detect --json\` to identify
+   which linter is configured. If more than one could host this rule,
+   ask the user which tool should own it.
+
+2. **Mine the repo's own rules first.** This is the highest-signal
+   source for house style. Look at how the repo already writes rules of
+   this kind:
+   - existing config (e.g. \`.eslintrc*\`/\`eslint.config.*\`, \`ruff.toml\`
+     or \`[tool.ruff]\`, \`.rubocop.yml\`, \`.stylelintrc*\`);
+   - any custom/local rules the repo authored (the \`detect\` output's
+     rule styles point at these);
+   - the conventions, severity choices, and naming they use.
+   Match that style.
+
+3. **Fall back to the web only if the repo signal is thin.** If the repo
+   doesn't show how to express this rule, fetch the linter's CURRENT
+   documentation (WebFetch/WebSearch). Prefer the latest version's docs
+   and, when present, an \`llms.txt\` on the tool's docs site. Confirm the
+   installed version where it matters so you target the right syntax.
+
+4. **Author the rule in the tool's dialect.** Write or extend the
+   linter's config / custom-rule file the way that tool expects. Keep it
+   consistent with the repo's existing entries from step 2.
+
+5. **Report, and be explicit about who runs it.** Show the file(s) you
+   changed. Make clear that the user's OWN toolchain runs this rule:
+   \`%(TASKLESS_CLI)s check\` does NOT execute external linters. Tell the user how
+   to run their linter to see it fire (e.g. their existing lint script).
+
+## Important Notes
+
+- Do not invent linter rules from memory: verify against the repo's
+  usage and the tool's current docs.
+- This path is author-only. Taskless does not aggregate or run external
+  linters; it writes the rule in the tool's dialect and hands off.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: re-decide the destination if this no longer fits
+- \`%(TASKLESS_CLI)s agent create-sg-rule\`: author a local ast-grep rule instead
+- \`%(TASKLESS_CLI)s agent create-remote-rule\`: generate via the service (login)
+`, J = `# Topic: create-remote-rule     (CLI v%(CLI_VERSION)s / topic v3)
+
+## You are here
+This is \`create-remote-rule\`. It helps you have the Taskless service
+write a rule, when the rule is beyond what you can express on-device or
+the user has chosen to spend a generation on it.
+If that is not the kind of check you need, re-run \`%(TASKLESS_CLI)s agent route\`
+and follow its decision rather than adapting this recipe.
+
+## Goal
+Enrich the user's description into a request the service can act on,
+submit it, and report what came back. The service generates the rule and
+writes the rule files; your job is everything on either side of that
+call.
+
+This recipe is the whole path, the boundary and the procedure. Do not
+go looking for a second topic to perform the submission.
+
+## Preconditions
+- \`.taskless/\` directory exists.
+- The user is logged in. This path requires auth.
+- The project has a GitHub owner. **Check this yourself before collecting
+  anything**, see below.
+- The request reached here through \`route\`, or through a local attempt
+  that failed and a user who confirmed the escalation.
+
+### Check the GitHub owner first
+
+Generation runs against a verifiable org, which comes from a GitHub
+\`origin\` remote. Run:
+\`\`\`
+%(TASKLESS_CLI)s info --json
+\`\`\`
+If \`ghOwner\` is the literal \`[unknown]\`, **stop here**. Do not enrich the
+request, do not collect examples, and do not submit: the call cannot
+succeed, and everything before it is wasted work for the user.
+
+Say the tier is unavailable and why, then route to a local recipe:
+\`create-sg-rule\`, \`create-vale-rule\`, or \`create-legacy-rule\` by the
+rule's shape, or \`create-runtime-rule\` if it is only expressible at
+runtime.
+
+\`route\` already drops this destination when there is no owner, so
+normally you never arrive here without one. This check is for the times
+that does not hold: reached directly, from a cached plan, or from a copy
+of the routing guidance older than this constraint. An omission upstream
+is advisory; this is the point of use.
+
+**\`auth login\` does not fix it.** No GitHub owner is a property of the
+project, not the session, so do not send the user to log in for it. The
+causes are: not a git repository, no \`origin\` remote, an \`origin\` that is
+not GitHub, and git not being installed at all. The first three each have
+their own error code; a missing \`git\` binary cannot be told apart from
+the first, because the probe that would distinguish them is itself a
+\`git\` call, so it reports \`NOT_A_GIT_REPOSITORY\`. If the user says the
+directory *is* a repository, check whether \`git\` is on their \`PATH\`
+before believing the code.
+
+## Cost, and when this path is right
+
+A generation costs the user something and requires an account. That is
+why \`route\` prefers a local rule it can write and verify, and why this
+recipe is not a default.
+
+Two ways to legitimately be here:
+
+- **\`route\` sent you.** Either the rule is not expressible on-device, or
+  it is expressible and the user was offered the choice and took it.
+- **A local attempt failed and the user confirmed.** If you came from
+  \`create-sg-rule\`'s failure path, that recipe has already deleted the
+  broken candidate and asked. If it has not been asked, ask now, a
+  silent fall-through from a failed local attempt to a paid service call
+  is not acceptable, even when the service would do better.
+
+## Steps
+
+1. **Confirm auth.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s info --json
+   \`\`\`
+   Check \`loggedIn\`. If false, fetch \`%(TASKLESS_CLI)s agent auth\` and follow the
+   login recipe before continuing. Do not build a request you cannot
+   submit.
+
+2. **Check for a rule that already covers this.** Scan
+   \`.taskless/rules/sg/\` and read each rule's \`message\`, \`note\`, and
+   \`rule\` fields. If one overlaps, show the user and ask whether they
+   would rather iterate on it, \`%(TASKLESS_CLI)s agent improve-rule\` refines an
+   existing rule and is usually the better answer than a second rule
+   that half-overlaps the first.
+
+3. **Gather the request.** Even when the user supplied a description,
+   ask:
+   - What exact pattern should be flagged? Get concrete examples.
+   - In what language?
+   - Where is the pattern acceptable: are there contexts to exclude?
+
+   If you arrived from a failed local attempt, reuse the cases you
+   already gathered rather than asking again.
+
+4. **Enrich it.** This is the part that decides the quality of what
+   comes back:
+   - Search the codebase for real instances and show the user what you
+     found. Real matches beat invented ones.
+   - Ask for further success and failure cases, especially near-misses.
+   - Read \`.gitignore\`, the linter configs, and \`tsconfig.json\`'s
+     \`exclude\` for exclusion patterns the repo already believes in.
+     Present them as proposed defaults rather than applying them.
+   - Infer the primary language from the codebase and confirm it. Put it
+     in the \`prompt\` field.
+
+5. **Confirm before spending the generation.** Summarize the full
+   prompt, the success cases, the failure cases, and the exclusions.
+   This is the last point at which a misunderstanding is free.
+
+6. **Write the payload** to \`.taskless/.tmp-rule-request.json\`, matching
+   the input schema below.
+
+7. **Submit.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s rule create --from .taskless/.tmp-rule-request.json --json
+   \`\`\`
+   This may take 30-60 seconds while the service generates the rule.
+
+8. **Clean up.** Delete \`.taskless/.tmp-rule-request.json\` whether the
+   call succeeded or failed.
+
+9. **Report.** The service writes the rule to
+   \`.taskless/rules/sg/<id>/<id>.yml\` and its tests to
+   \`.taskless/rules/sg/<id>/.tests/<id>-YYYYMMDD-test.yml\`. These are
+   the same paths and the same shape a locally authored rule uses, so
+   \`check\`, \`improve-rule\`, \`verify\`, and \`test\` treat them
+   identically. Nothing is written under \`.taskless/rule-metadata/\`.
+   Show the user the paths and suggest \`%(TASKLESS_CLI)s agent check\`.
+
+   **Record the \`ruleId\` from the \`--json\` output.** It is the ticket
+   id the iterate endpoint is addressed by, \`improve-rule\` asks for it,
+   and no file on disk carries it.
+
+   **Read \`notices\` if it is present.** It is an optional array of
+   advisory messages about a delivery that was written anyway. A rule
+   arriving with no \`.tests/\` fixtures is the one to expect. That rule works, but
+   nothing exercises it: \`test\` reports a pass over zero cases, which
+   reads exactly like a rule proven to work. Surface any notice to the
+   user rather than reporting an unqualified success. Under \`--json\`
+   these do not go to stderr, so the envelope is the only place they
+   appear.
+
+## Input schema
+
+The \`--from\` JSON file conforms to:
+
+\`\`\`json
+%(INPUT_SCHEMA)s
+\`\`\`
+
+Each entry in \`successCases\` and \`failureCases\` is a separate string.
+Multi-line code goes in one string with literal newlines.
+
+## Important Notes
+
+- Do NOT pre-build the rule yourself here. Submit the request and let
+  the service generate it; a hand-written rule attached to a generation
+  request is neither reviewed nor used.
+- The service owns rule-type selection. Today it generates ast-grep
+  rules under \`.taskless/rules/sg/\`, the same shape \`create-sg-rule\`
+  produces locally.
+
+## Errors
+
+With \`--json\`, failures emit \`{ ok: false, code, message }\`:
+
+| code                     | meaning                         | fix                                          |
+|--------------------------|---------------------------------|----------------------------------------------|
+| \`AUTH_REQUIRED\`          | not logged in                   | fetch \`%(TASKLESS_CLI)s agent auth\`          |
+| \`NO_GITHUB_REMOTE\`       | no GitHub origin remote         | retained for compatibility; treat as below   |
+| \`NOT_A_GIT_REPOSITORY\`   | not a git repository            | route to a local recipe; \`auth login\` cannot fix it |
+| \`NO_ORIGIN_REMOTE\`       | git repository, no \`origin\`     | route to a local recipe; \`auth login\` cannot fix it |
+| \`UNSUPPORTED_REMOTE_HOST\`| \`origin\` is not GitHub          | route to a local recipe; \`auth login\` cannot fix it |
+| \`INVALID_INPUT\`          | \`--from\` JSON failed validation | re-read the input schema, fix, retry         |
+| \`NETWORK_ERROR\`          | submit/poll failed              | report and suggest retry                     |
+| \`RULE_GENERATION_FAILED\` | the service failed to generate  | report the message; suggest enriching prompt |
+| \`RULE_UNSUPPORTED\`       | plan lacks this generation type | tell the user to enable it; do not retry     |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: the routing decision that leads here
+- \`%(TASKLESS_CLI)s agent auth\`: log in before generating
+- \`%(TASKLESS_CLI)s agent create-sg-rule\`: author a rule locally instead
+- \`%(TASKLESS_CLI)s agent improve-rule\`: iterate on a rule that already exists
+- \`%(TASKLESS_CLI)s agent check\`: validate the generated rule
+`, Q = `# Topic: create-runtime-rule     (CLI v%(CLI_VERSION)s / topic v2)
+
+## You are here
+This is \`create-runtime-rule\`. It helps you write a runtime rule: a
+check that runs your own code, because answering it needs more than one
+file, the repository graph, git metadata, build output, a resolved
+config chain.
+If that is not the kind of check you need, re-run \`%(TASKLESS_CLI)s agent route\`
+and follow its decision rather than adapting this recipe.
+
+You are reading this recipe rather than \`create-remote-rule\` because the
+user is **not logged in**. That is the whole difference, and this recipe
+explains it once.
+
+## Goal
+Explain what a runtime rule is, why this tier is gated when the static
+tiers are not, and what the user has to do before one can run.
+
+## Preconditions
+- \`.taskless/\` directory exists.
+- The user is **not** logged in. If \`%(TASKLESS_CLI)s info --json\` reports
+  \`loggedIn: true\`, you are in the wrong recipe, re-run
+  \`%(TASKLESS_CLI)s agent route\`.
+
+## What a runtime rule is
+
+A rule directory under \`.taskless/rules/runtime/<name>/\` holding two
+kinds of file:
+
+| Path             | Role                                                                      |
+|------------------|---------------------------------------------------------------------------|
+| \`captures/*.yml\` | ast-grep capture rules that narrow which files the check looks at         |
+| \`check.ts\`       | a module whose default export receives those matches and returns findings |
+| \`.tests/\`        | fixtures, in \`pass/\` and \`fail/\` buckets                                  |
+
+A fixture case is a DIRECTORY, not a file: \`.tests/pass/case-1/\`, and its
+path is the \`root\` the harness hands the check, with every \`match.file\`
+relative to it. So a case may hold as many files as the case needs.
+
+That is not a detail. A runtime rule exists because its evidence spans
+more than one file, so a layout allowing one file per case could not
+express the rules the tier is for. \`pass/case-1/src/a.ts\` alongside
+\`pass/case-1/src/b.ts\` is the ordinary shape, not the exotic one.
+
+\`pass\`/\`fail\` rather than \`valid\`/\`invalid\`, matching Vale's buckets.
+\`valid\`/\`invalid\` are key names inside an ast-grep test YAML and are
+right for \`sg\` for one reason only: that file is handed to \`sg test\`
+verbatim. Nothing hands a runtime fixture to ast-grep, so borrowing the
+word here would make it mean two things.
+
+\`verify\` fails a runtime rule with no capture rule in \`captures/\`,
+because \`check.ts\` would then never be invoked.
+
+The capture rules do the cheap work, if nothing matches, \`check.ts\` is
+never invoked. \`check.ts\` does the part no static engine can: hold two
+files at once, read git, resolve an alias, look outside the repository.
+
+That is also exactly why it is gated.
+
+## Why this tier is gated
+
+**Because it executes code, not because of what it can express.**
+
+\`sg\` and \`vale\` rules are inert data. Whatever is in them, the worst a
+malicious rule achieves is a wrong finding, \`%(TASKLESS_CLI)s check\` runs them
+with no login, no network, and nothing to verify, because there is
+nothing to verify.
+
+A runtime rule's \`check.ts\` is a program that runs on the developer's
+machine with the developer's permissions. A rule file that arrives in a
+pull request is code that arrives in a pull request. So \`check\`:
+
+1. **Signs** each \`check.ts\`, a signature over the exact bytes on disk.
+2. **Reconciles** those signatures with the Taskless service, which
+   answers with the set it will vouch for.
+3. **Runs only what came back blessed.** Anything else is reported as
+   skipped, with the reason.
+
+Reconciliation is what makes the signature mean something: it is the
+service saying "this rule, these exact bytes, for this repository."
+Without a login there is nobody to ask, so there is no answer, so
+nothing runs.
+
+This is a property of executing code. It says nothing about whether a
+runtime rule is more or less capable, and it is not a quality tier:
+\`sg\` and \`vale\` rules are not less trusted, they are unexecuted.
+
+## What happens today, logged out
+
+Nothing breaks. \`%(TASKLESS_CLI)s check\` still runs every static rule; each
+runtime rule it finds is listed as skipped with the reason
+\`not authenticated, runtime rules were not verified and did not run\`.
+
+So a runtime rule you write now is inert until the user logs in. Say
+that plainly rather than letting them discover it from a silent check.
+
+## Testing a rule you wrote yourself needs the flag
+
+\`%(TASKLESS_CLI)s test\` runs a runtime rule's fixtures by executing its
+\`check.ts\` against each case directory. The flag is the whole gate, for
+every rule, always:
+
+\`\`\`
+%(TASKLESS_CLI)s test .taskless/rules/runtime/<name> --dangerously-run-scripts
+\`\`\`
+
+**\`test\` does not talk to the rule service at all**, and there is no
+blessed-signature path that runs fixtures without the flag. That makes
+it stricter than \`check\`, which will execute a blessed rule with no flag
+because it runs rules as a side effect of scanning a repository. \`test\`
+runs them because you asked it to, so the verb is the consent and the
+flag is the confirmation; nothing is asked of a server in between.
+
+**A locally authored rule has no signature and never will**, so this was
+never going to be avoidable for a rule you wrote. Blessing is recording:
+a signature is blessed because a reconcile reported it and the service
+recorded it, and nothing recorded a rule that has not left the working
+tree. Do not send anyone to \`auth login\` over this. It changes nothing
+here, and the message does not mention it.
+
+The friction is the correct friction. \`sg\` and \`vale\` authors do not
+face it because their rules are unexecuted. A delivered rule and one you
+wrote a minute ago are indistinguishable on disk, so an exemption for
+"my own rule" would be an exemption for any rule, and the warning the
+flag prints is accurate in both cases.
+
+Without the flag \`test\` prints \`○\` for the rule, says the fixtures did
+not run, names the flag, and exits 0. That is neither a pass nor a
+failure, and it is deliberately not a failure: nothing the holder of an
+unblessed rule can do would make a failure green.
+
+Both buckets have to be populated for the rule to pass, and every case
+has to match at least one capture. A case the captures do not match
+never reaches \`check.ts\`, and is reported as a defect in the case rather
+than in the rule, in \`pass/\` as well as \`fail/\`: such a case proves the
+capture did not match, which is a fact about the fixture.
+
+## Steps
+
+1. **Tell the user what their rule needs, and why it is gated.** Name
+   the evidence, "this has to compare two files", "this reads git
+   history", and then the consequence: it has to run code, so it needs
+   an account. Do not present this as a limitation of the rule.
+
+2. **Point them at login.** Obtaining access is \`auth\`'s job, and this
+   recipe deliberately does not restate it:
+
+   \`\`\`
+   %(TASKLESS_CLI)s agent auth
+   \`\`\`
+
+   Follow that recipe with the user. If they do not want an account,
+   stop here, say the rule cannot run without one, and offer to
+   reconsider whether a narrower version of the request could be
+   answered by a static rule instead. That is a new routing decision,
+   not a fallback you take on their behalf.
+
+3. **Once they are logged in, re-route.** Run
+   \`%(TASKLESS_CLI)s info --json\` to confirm \`loggedIn: true\`, then
+   re-run \`%(TASKLESS_CLI)s agent route\` with the original request. The
+   destination changes now that the gate is open.
+
+## Important Notes
+
+- \`--dangerously-run-scripts\` makes \`check\` and \`test\` execute runtime
+  rules without server verification. It exists for local iteration on a
+  rule you wrote yourself and just read, which includes running its
+  fixtures. On \`test\` it is the only mechanism there is. It is not a way
+  to ship a rule to a team, and suggesting it to work around a login
+  turns a deliberate gate into an unreviewed code-execution path on
+  someone else's machine.
+- Do not author a \`check.ts\` and leave it in the repository unmentioned.
+  A skipped runtime rule reports nothing, which reads exactly like a
+  passing one.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent auth\`: log in, log out, check status
+- \`%(TASKLESS_CLI)s agent route\`: re-decide once the login state changes
+- \`%(TASKLESS_CLI)s agent check\`: see which rules ran and which were skipped
+`, Z = '# Topic: create-sg-rule     (CLI v%(CLI_VERSION)s / topic v5)\n\n## You are here\nThis is `create-sg-rule`. It helps you write an ast-grep rule: a check\nover the structure of a single source file, authored on this machine.\nIf that is not the kind of check you need, re-run `%(TASKLESS_CLI)s agent route`\nand follow its decision rather than adapting this recipe.\n\n## Goal\nProduce a verified ast-grep rule and its test file, locally, without\ncontacting the Taskless service. You derive the rule yourself, write it\nin the canonical on-disk shape, and validate it with `verify` and\n`test` in a feedback loop. The files you produce match exactly what the\nservice writes, so `check`, `improve-rule`, `verify`, and `test` treat\nthem identically.\n\n## Preconditions\n- `.taskless/` directory exists.\n- The agent can read/write files and run shell commands.\n- No auth required.\n\n## One rule, one directory\n\nEverything defining a rule lives in `.taskless/rules/sg/<id>/`. Writing\na rule means creating that directory; deleting a rule means deleting\nit. No file outside it is touched either way, so two agents authoring\ntwo rules never collide.\n\n```\n.taskless/rules/sg/no-eval/\n    no-eval.yml                       the rule\n    .tests/no-eval-YYYYMMDD-test.yml  its test cases\n```\n\n**The leading dot on `.tests/` is required.** ast-grep walks the rules\ntree and parses every `.yml` it reaches as a rule, so a plain `tests/`\ndirectory makes it read your test file as a rule and fail the scan for\nthe whole project. A dot-directory is skipped by that walk, and the\ntest runner still finds it. Do not rename it.\n\nUnlike Vale, an `sg` rule needs no second config file. It carries its\nown `files` and `ignores` inside the rule, so the rule file is the\nwhole rule.\n\n## Steps\n\n1. **Learn the ast-grep rule format.** Consult the ast-grep rule\n   reference at https://ast-grep.github.io/guide/rule-config.html for\n   valid fields and operators (`pattern`, `kind`, `regex`,\n   `any`/`all`/`has`/`inside`/`not`) and meta-variable syntax. This\n   recipe does not embed the schema. Read it from upstream rather than\n   writing a rule from memory.\n\n2. **Gather and confirm the pattern.** Make sure you have concrete\n   success cases (code that should pass) and failure cases (code that\n   should be flagged), the target language, and any exceptions. Search\n   the codebase for real instances and confirm exclusions with the user.\n\n3. **Check for an existing rule that already covers this.** Scan\n   `.taskless/rules/sg/` and read each rule\'s `message`, `note`, and\n   `rule` fields. If one overlaps, show the user and ask whether they\n   would rather improve it, `%(TASKLESS_CLI)s agent improve-rule --anonymous`\n   iterates a rule locally.\n\n4. **Author the rule in the canonical shape.** Write the rule to\n   `.taskless/rules/sg/<id>/<id>.yml`, where `<id>` is kebab-case and\n   names both the directory and the file. At minimum:\n   - `id`: kebab-case, matching the filename (e.g. `no-eval`)\n   - `language`: the target language, in ast-grep\'s spelling (below)\n   - `severity`: `error`, `warning`, `info`, or `hint`\n   - `message`: a concise single-line explanation\n   - `rule`: the ast-grep rule object\n\n   Optional but useful: `note` (multi-line guidance, supports markdown),\n   `fix` (auto-fix pattern), `ignores` (file patterns to skip).\n\n   **`language` is ast-grep\'s vocabulary.** The vendored rule schema\n   types the field as a bare string with no enum, so the schema layer\n   accepts anything. `verify` checks it separately: an off-list spelling\n   is an error naming the accepted list, and a spelling ast-grep resolves\n   but does not itself use (`typescript` for `TypeScript`) is a notice.\n   Get it right anyway rather than leaning on that check. An unrecognized\n   name aborts config parsing, which takes every other sg rule in the\n   project down with it and reports nothing.\n   ast-grep (v%(AST_GREP_VERSION)s) parses:\n\n     %(AST_GREP_LANGUAGES)s\n\n   Copy a spelling from that list rather than typing one that looks\n   right. Off-list spellings fail two different ways and neither is\n   caught locally: one ast-grep does not recognize at all takes the\n   whole scan down (`did not match any variant of untagged enum\n   SgLang`, so every other rule goes unreported too), and one it\n   recognizes but that names the wrong parser reports nothing and looks\n   like a clean codebase.\n\n   Two specific traps:\n   - **Do not copy from `detect --json`.** It reports the\n     *repository\'s* languages in a different vocabulary. It says\n     `C++` where the list above says `Cpp`.\n   - **`Tsx` and `TypeScript` are two parsers, not aliases.** A rule\n     over `.tsx` files that declares `TypeScript` does not match JSX\n     syntax; it does not read those files at all.\n   - **`Markdown` sees blocks only.** tree-sitter-markdown splits\n     block and inline grammars and ast-grep exposes only the block\n     tree, so `atx_heading`, `setext_heading`, `fenced_code_block`,\n     `list_item`, `paragraph`, `section` and `document` are real kinds\n     and everything inside a line is one opaque `inline` node. There is\n     no `link`, `emphasis` or `strong_emphasis` kind; naming one is a\n     config error that exits 8 and takes the whole scan with it, and\n     writing it as a pattern (`[$T]($U)`) matches nothing forever with\n     no error at all. A rule about the words inside a line belongs to\n     Vale, not here. ast-grep also has no count and no absence\n     assertion, so "every doc has an h1" is not expressible as an `sg`\n     rule at any severity.\n\n5. **Check any variadic pattern against the separator trap.** A `$$$`\n   next to a comma does not mean "zero or more". The `,` in the pattern\n   is itself an AST node, and under ast-grep\'s default `smart`\n   strictness every node in the pattern must match, so a call with no\n   comma cannot match a pattern that has one. Measured against the\n   ast-grep this CLI ships (v%(AST_GREP_VERSION)s), given the four calls\n   `foo()`, `foo(1)`, `foo(1,2)`, and `foo(1,2,3)`:\n\n| pattern            | what it matches                              |\n|--------------------|----------------------------------------------|\n| `foo($$$)`         | all four, `foo()` included                   |\n| `foo($A, $$$)`     | `foo(1,2)` and `foo(1,2,3)`, never `foo(1)` |\n| `foo($$$, $A)`     | `foo(1)` alone                               |\n| `foo($A, $$$, $B)` | `foo(1,2)` alone                             |\n\n   A standalone `$$$` needs none of this. It is the comma beside it\n   that narrows the pattern. The two remedies are not the same:\n\n   - **Trailing `$$$`**: write the pattern as an object with\n     `strictness: ast`, which compares named AST nodes and ignores the\n     separator. An object pattern also requires `context` and\n     `selector`:\n     ```yaml\n     rule:\n       pattern:\n         context: foo($A, $$$)\n         selector: call_expression\n         strictness: ast\n     ```\n     This moves the boundary from two arguments to one, **not to\n     zero**, `$A` still has to bind something, so `foo()` is still\n     unmatched. And `strictness` is valid only inside the pattern\n     object: at rule level ast-grep rejects it as an unknown field and\n     fails the whole scan.\n   - **Leading `$$$`**: `strictness: ast` does not rescue it. Use\n     `any` with one branch per arity you mean to cover.\n\n   This is upstream\'s intended behaviour (ast-grep/ast-grep#1365,\n   closed as working-as-intended), not a bug waiting on a release:\n   0.45.2 behaves identically, so there is no version to wait for.\n\n6. **Write the tests.** Write\n   `.taskless/rules/sg/<id>/.tests/<id>-YYYYMMDD-test.yml` with the matching\n   `id` field plus `valid` and `invalid` arrays, at least two of each,\n   drawn from real code where you can. The `id` must match the rule\'s\n   `id` so ast-grep test filtering pairs them. These paths and this\n   shape are the same ones the service writes; do not invent a different\n   layout.\n\n   **Both arrays must be non-empty, and `test` fails the rule if either\n   one is.** An empty `invalid:` is not a neutral starting point to fill\n   in later: ast-grep reports `1 passed; 0 failed` and exits zero over\n   no cases at all, so a rule that matches nothing anywhere looks\n   exactly like a rule that works. The `invalid:` bucket is the only\n   thing that demonstrates the rule can fire.\n\n   Where the rule has an arity boundary (anything from step 5), put a\n   case on each side of it. A pattern that starts at two arguments when\n   it was meant to start at one passes a test suite whose fixtures all\n   have two.\n\n7. **Run the verify feedback loop.** Both commands take the rule\'s\n   directory as their argument:\n   ```\n   %(TASKLESS_CLI)s verify .taskless/rules/sg/<id> --json\n   %(TASKLESS_CLI)s test   .taskless/rules/sg/<id> --json\n   ```\n   `verify` asks whether the rule is well-formed: the YAML matches the\n   ast-grep schema and every Taskless-required field is present. It\n   needs no test file, so run it the moment the rule exists. `test` runs\n   the cases, after running `verify` and stopping if that fails, so a\n   malformed rule reports the malformation rather than a test complaint.\n\n   Both answer in the same shape:\n   ```json\n   {"ok":true,"rules":[{"engine":"sg","ruleId":"no-eval",\n    "ok":true,"errors":[],"ran":true}]}\n   ```\n   - `ok: true` → go to step 8.\n   - `ok: false` → read `errors` and fix. Repeat up to 3 times.\n\n| what `errors` says                   | fix                                             |\n|--------------------------------------|-------------------------------------------------|\n| the YAML doesn\'t match the schema    | check field types against the upstream schema   |\n| a Taskless-required field is missing | add `id`/`language`/`severity`/`message`/`rule` |\n| a case didn\'t behave as expected     | fix the rule pattern OR the test case           |\n\n   A `regex` without an accompanying `kind` fails verification, the two\n   always travel together.\n\n   Pass a directory above a rule and every rule beneath it is checked,\n   one entry per rule in the report. `.taskless/rules/sg` covers every\n   ast-grep rule; no argument at all covers the project.\n\n8. **On success, report.** Show the rule directory and what is in it,\n   plus a one-line summary of what the rule detects. Suggest\n   `%(TASKLESS_CLI)s agent check` to validate against the broader codebase.\n\n9. **On failure, escalate, with confirmation.** If after the feedback\n   loop the rule still cannot capture the user\'s cases:\n   - Delete the candidate `.taskless/rules/sg/<id>/` directory so the\n     repo is not left with a broken rule. One `rm -rf` removes the rule\n     and its tests together.\n   - Tell the user the local rule could not capture the cases, and that\n     generating via the Taskless service uses a generation and requires\n     login.\n   - Only after the user confirms, fetch `%(TASKLESS_CLI)s agent\n     create-remote-rule` and follow it. Do not call the service silently.\n\n## Two ways a relational rule matches nothing\n\nBoth of these parse, verify, run, and exit 0. Neither reports anything\never, which reads exactly like a clean codebase.\n\n**`follows` and `precedes` need `stopBy: end` to cross punctuation.**\nA sibling relation walks the immediate siblings, and in most grammars\nthe separators are nodes too. Between two array elements sits a `,`, so\nthe previous element is not the previous SIBLING. Measured on\nTypeScript, `[10, 10, 30]` with\n\n```\nrule:\n  kind: number\n  follows: { kind: number }\n```\n\nmatches nothing, and the same rule with `stopBy: end` inside `follows`\nmatches. If a sibling relation reports zero on input you believe should\nmatch, add `stopBy: end` before doubting the rest of the rule.\n\n**A `not` containing a bare metavariable excludes everything.** Writing\n"the name is not used in the initializer" as\n\n```\nrule:\n  kind: variable_declarator\n  has: { field: name, pattern: $A }\n  not:\n    has: { pattern: $A, stopBy: end }\n```\n\nmatches nothing at all, because `$A` is bound to the name node and that\nnode is its own descendant: the `not` finds it inside every declarator\nand rejects all of them. Scope the negation to the part you meant, in\nthis case the value:\n\n```\n  not:\n    has:\n      field: value\n      has: { pattern: $A, stopBy: end }\n```\n\nThe general shape: when a `not` searches the same subtree that bound the\nmetavariable, it always finds it.\n\n## Important Notes\n\n- Do NOT make any HTTP requests to taskless.io on this path.\n- Do NOT write to `.taskless/rule-metadata/`: no rule has a metadata\n  sidecar, service-generated ones included, because the CLI never\n  writes that directory. Locally authored rules iterate via file edits.\n- The verify loop is the quality gate. A clean failure is a legitimate\n  reason to escalate, but only with the user\'s confirmation (step 9).\n\n## See Also\n\n- `%(TASKLESS_CLI)s agent route`: re-decide the destination\n- `%(TASKLESS_CLI)s agent verify-rule`: the `verify` and `test` commands step 7 calls\n- `%(TASKLESS_CLI)s agent improve-rule`: iterate on a rule that already exists\n- `%(TASKLESS_CLI)s agent create-remote-rule`: generate via the service (login)\n- `%(TASKLESS_CLI)s agent check`: validate the new rule against the codebase\n', ee = '# Topic: create-vale-rule     (CLI v%(CLI_VERSION)s / topic v8)\n\n## You are here\nThis is `create-vale-rule`. It helps you write a Vale rule: a check over\nthe words of a document, prose, markup, and the prose parts of code.\nIf that is not the kind of check you need, re-run `%(TASKLESS_CLI)s agent route`\nand follow its decision rather than adapting this recipe.\n\n## Goal\nProduce a Vale rule that fires on the prose it should flag and stays\nquiet on the prose it should not, scoped to the files it is about.\n\n## Preconditions\n- `.taskless/` directory exists.\n- The agent can read/write files and run shell commands.\n- No auth required.\n\n## One rule, one directory\n\nEverything that defines a Vale rule lives in\n`.taskless/rules/vale/<id>/`. Writing a rule means creating that\ndirectory. Deleting a rule means deleting it. No file outside it is\ntouched either way, so two agents authoring two rules never collide.\n\n```\n.taskless/rules/vale/no-simply/\n    no-simply.yml          the style: what the rule looks for\n    .vale.ini              the scope: which files it applies to\n    .tests/fail/bad.md     prose it must flag\n    .tests/pass/ok.md      prose it must leave alone\n```\n\nThe rule is **incomplete until the style and the config both exist**,\nand skipping the config fails silently rather than loudly: the rule\nparses, the check passes, and nothing is ever reported. `verify` exists\nto catch exactly that, so run it (step 6) before you believe a rule\nworks.\n\n**The id appears four times and all four must agree:**\n\n```\n.taskless/rules/vale/no-simply/           <- the directory\n.taskless/rules/vale/no-simply/no-simply.yml   <- the style file\nno-simply.no-simply = YES                 <- the assignment in .vale.ini\ntskl) rule = no-simply                    <- the breadcrumb in .vale.ini\n```\n\nThe doubled `no-simply.no-simply` is not a typo. Vale names a check\n`<style>.<rule>`, and here the rule\'s own directory is the style, so\nboth halves are the id. Anything else is a check that does not exist,\nwhich Vale accepts without complaint.\n\nYou will not find a project-wide `.vale.ini` to edit. The config Vale\nactually reads is assembled from every rule\'s own file at check time\nand is gitignored. Editing it is pointless, the next check regenerates\nit.\n\n## Steps\n\n1. **Say what the rule reads, then pick an extension point.** Write one\n   sentence: "this fires when a document contains ___." Vale rules are\n   built by extending one of its twelve checks, and the sentence tells\n   you which. Twelve is measured, not counted off the docs: give Vale\n   v%(VALE_VERSION)s an `extends` it does not know and it names the whole\n   set back at you:\n\n   ```\n   \'extends\' key must be one of [capitalization conditional consistency\n   existence occurrence repetition substitution readability spelling\n   sequence metric script].\n   ```\n\n   The docs enumerate eleven, folding `readability` into `metric`. They\n   are separate checks with separate fields.\n\n| If the rule is about…                                                                   | extends          |\n|-----------------------------------------------------------------------------------------|------------------|\n| words or phrases that should not appear                                                 | `existence`      |\n| preferring one term over another. **including the correct spelling of a product name** | `substitution`   |\n| the case of a whole heading or sentence                                                 | `capitalization` |\n| how many times something may appear                                                     | `occurrence`     |\n| a word repeated back to back                                                            | `repetition`     |\n| picking one of two acceptable spellings, consistently                                   | `consistency`    |\n| "if X appears, Y must also appear"                                                      | `conditional`    |\n| a length or ratio threshold, over the document or one `scope` of it                     | `metric`         |\n| a readability grade, against a named formula                                            | `readability`    |\n| a misspelling, against a dictionary                                                     | `spelling`       |\n| phrases that must appear in a fixed order                                               | `sequence`       |\n| anything the above cannot express (Tengo script)                                        | `script`         |\n\n   **`capitalization` is about a whole scope, not a word.** It asks\n   whether an entire heading or sentence matches a case pattern. It\n   cannot express "the word GitHub, wherever it appears, is spelled\n   thus". That is a `substitution`, because you are swapping a wrong\n   spelling for a right one. Reaching for `capitalization` on a product\n   name produces a rule that flags whole sentences: measured, a rule with\n   `match: GitHub` reports `We host on Github and it is fine. should be\n   GitHub`.\n\n   For the five this recipe has no worked example of, `metric`,\n   `readability`, `spelling`, `sequence`, `script`, read\n   https://docs.vale.sh/styles before inventing something. Vale has no\n   facility for a rule that does not extend one of these twelve, and an\n   `extends` outside the set is not a rule that misbehaves: Vale exits 2\n   and **every** Vale rule in the project goes unreported for that run.\n   `verify` rejects it before Vale is invoked, and names the twelve.\n\n   **The other seven have a worked rule at the end of this recipe**,\n   nine rules between them, each with the near-miss that fails and why.\n   Read the one closest to your intent before writing anything, the\n   mistakes documented there are observed, and most of them fail\n   silently.\n\n2. **Write the style file** to\n   `.taskless/rules/vale/<id>/<id>.yml`, where `<id>` is kebab-case and\n   names both the directory and the file.\n\n   **One exception: a `consistency` rule\'s id must be word characters\n   only** (`izeise`, not `ize-ise`). That check compiles the id into its\n   pattern as a regex group name, and a hyphen there fails the entire\n   Vale run. `verify` catches it. Kebab-case is correct for the other\n   eleven.\n\n   Every rule carries:\n\n| Field     | Required | Notes                                         |\n|-----------|----------|-----------------------------------------------|\n| `extends` | yes      | one of the twelve above                       |\n| `message` | yes      | shown to the user; see the `%%s` table below  |\n| `level`   | no       | `suggestion` (default), `warning`, or `error` |\n| `scope`   | no       | narrow to part of a document; see below      |\n| `link`    | no       | a URL the reader can follow for the reasoning |\n| `limit`   | no       | cap findings from this rule per scope         |\n\n   **`vocab` is not one of these.** It reads as though it were, but it is\n   a per-check field: measured, only `existence`, `substitution`,\n   `capitalization`, `conditional` and `repetition` accept it, and\n   `occurrence`, `metric`, `readability`, `script` and `sequence` reject\n   it. On one of those five it raises `E201` and takes every other Vale\n   rule in the project down with it. It is listed with the per-check\n   fields below.\n\n   **The file extension must be `.yml`.** Measured: rename a working\n   style file to `.yaml` and Vale loads nothing, no error, no warning,\n   zero findings, and `<id>.<id> = YES` still parses. It is\n   indistinguishable from a rule whose pattern never matched.\n\n   **`scope` decides where the rule looks**, so getting it wrong is a\n   silent under-fire rather than an error. An unrecognized scope is not\n   rejected by Vale: `scope: fenced` loads, runs, and matches nothing.\n   It is the worst of the three failures on this page, because unlike a\n   bad `extends` or a foreign field it does not even take the run down to\n   tell you. The rule is inert, forever. `verify` rejects a scope\n   outside the table below, which is the only layer that ever will.\n\n   Every value below was measured against Vale v%(VALE_VERSION)s by\n   authoring a rule with that scope and a document the rule had to flag.\n   "Fires" means the finding appeared; a scope that never fired is not on\n   this list.\n\n| `scope`                | reaches                                                   |\n|------------------------|-----------------------------------------------------------|\n| *(omitted)*            | everything the format exposes as prose                    |\n| `text`                 | prose only, not inline code, not fenced blocks           |\n| `code`                 | inline code spans only                                    |\n| `raw`                  | the unparsed document: prose, inline code, fenced blocks  |\n| `heading`              | every heading                                             |\n| `heading.h1`…`h6`      | headings of that level                                    |\n| `paragraph`            | one paragraph at a time                                   |\n| `sentence`             | one sentence at a time                                    |\n| `list`                 | list items                                                |\n| `blockquote`           | quoted blocks                                             |\n| `link`                 | link text, not the URL                                    |\n| `alt`                  | image alt text                                            |\n| `summary`              | `<summary>` of a disclosure                               |\n| `strong`, `emphasis`   | bold and italic runs                                      |\n| `table`                | any part of a table                                       |\n| `table.header`         | header cells                                              |\n| `table.cell`           | body cells                                                |\n| `table.caption`        | a table\'s caption                                         |\n| `figure.caption`       | a figure\'s caption, but see below                        |\n| `frontmatter`          | every YAML front-matter value                             |\n| `frontmatter.<key>`    | one front-matter key\'s value                              |\n| `text.class.<name>`    | HTML elements carrying that class                         |\n| `comment`              | every comment, in a comment-tier format                   |\n| `comment.line`         | `//`-style comments                                       |\n| `comment.block`        | `/* … */`-style comments                                  |\n| `doc(<selector>)`      | elements matched by a CSS selector; see below             |\n\n   **`doc(<selector>)` picks part of a document by CSS selector**, the\n   same way in every markup format, and a heading with everything under\n   it is a `section`, so one section of a document is\n   `doc(section:has(> h2:contains("Decision")))`. Chain it to narrow an\n   ordinary scope to that element: `text & doc(...)` is prose inside it,\n   `sentence & doc(...)` one sentence at a time inside it, `~doc(...)` is\n   everything outside it. On its own, `doc(...)` lints what is INSIDE the\n   element as one block, which is what `occurrence` (a section must say\n   "we will") and `metric` (a section runs over budget) want. Measured: a\n   `metric` with `scope: doc(section:has(> h2:contains("Consequences")))`\n   and `formula: words` counts that section\'s words, not the document\'s.\n\n   **A leaf element on its own is inert.** `doc(h2)` alone selects a\n   heading, and a heading has nothing inside it to lint as a block, so the\n   rule matches nothing, with no error anywhere. Write `text & doc(h2)`\n   for the heading\'s own text. The same holds for `doc(p)` and `doc(li)`.\n   `verify` accepts both spellings, because telling a leaf from a container\n   needs the document; `test` shows which one fires.\n\n   **The selector is Vale\'s to check, not `verify`\'s.** A selector Vale\n   cannot compile (`doc(h2[)`) fails the whole run at load with\n   `E201 invalid selector in \'doc(...)\'`, which `test` reports. A selector\n   that compiles and matches nothing is silent, like any scope with no\n   construct to find. `verify` checks that the term is `doc(` … `)` with\n   something between, and no more.\n\n   **`raw` subsumes `code` and `text`.** Measured on one document holding\n   the token in prose, in an inline span, and in a fenced block: `text`\n   found one, `code` found one, `[code, text]` found two, `raw` found all\n   three. If you want prose and inline code but not fenced blocks, write\n   the list, `raw` is not "a bit wider", it is everything.\n\n   **Vale drops everything inside a `<figure>` element.** Measured: a\n   `<figcaption>` nested in `<figure>` is invisible to *every* scope,\n   `text` and `raw` included, so a `scope: figure.caption` rule over a\n   normally-marked-up figure reports nothing and looks like a bad scope.\n   A bare `<figcaption>` is linted, and `figure.caption` fires on it. If a\n   fixture is not firing, check whether its subject is inside a `<figure>`\n   before you touch the pattern.\n\n   **`scope` also takes `~` and `&`.** `~code` is everything but inline\n   code; `text & ~code` chains two operands; a list (`[code, text]`) is a\n   union. All three parse and behave.\n\n   **A negation over a scope Vale does not know is a silent no-op.**\n   Measured: `~banana` and `text & ~banana` both fire on everything,\n   because there is no such scope to subtract. A typo inside a `~` does\n   not narrow the rule and does not widen it visibly. It removes the\n   exclusion you wrote the rule for. `verify` checks the operands inside\n   `~` and `&` as strictly as a bare one, for exactly this reason, the\n   one place it is deliberately stricter than Vale itself.\n\n   **`scope` is per-rule, and rules do not interact.** Taskless assembles\n   every rule\'s matchers into one config for the run, which invites the\n   assumption that one rule\'s `scope` narrows another\'s, or that two\n   rules over the same file compete. They do not: each check carries its\n   own scope and is evaluated independently. If a rule is over-firing,\n   the cause is in that rule\'s own `scope` and glob, never in a\n   neighbour\'s.\n\n   **A directive turns any rule off, `raw` included, as of Vale 3.20.0.**\n   `<!-- vale <id>.<id> = NO -->` opens a zone and `= YES` closes it.\n   Vale records the region each directive covers and suppresses any\n   alert located inside it, which reaches a `raw`-scoped rule too.\n   Through 3.19.0 a directive was applied to the *parsed* document and\n   `raw` reads the unparsed one, so a `raw` rule fired straight through\n   every zone: a rule about a shell command, a flag, or a package name\n   was exempt-or-remove with nothing in between. It is not any more.\n\n   One thing to know before writing one over a `raw` rule: at `raw`\n   scope the directive line is itself linted text. A rule whose token\n   appears in its own id matches the marker that silences it, and\n   reports a finding on the directive. Name the rule so its own id does\n   not contain the word it looks for.\n\n   **A zone is two lines, and no blank line may separate it from the\n   prose it wraps.** Measured on Vale 3.20.0:\n\n   - Inline at a list item\'s continuation indent works, and this is the\n     form to reach for. The pair covers the lines between it and\n     nothing else.\n   - At column 0 it works too, and it ends any list it interrupts.\n     Blocks that then reparse as indented code are already outside a\n     prose rule\'s reach, so a zone placed there can move coverage\n     rather than restore it.\n   - A pair separated from its prose by blank lines, at an indent past\n     the code-block threshold, suppresses nothing: what it wraps is not\n     prose any more. Nothing reports that, either.\n\n   Through 3.19.0 the first of those did nothing at all. An inline pair\n   was read once per block, so the `NO` and the `YES` cancelled out\n   before the paragraph was linted and the words stayed reported with\n   no error and no warning. A zone had to wrap a whole step or a whole\n   section at the margin, and exempting the two steps of this recipe\n   that quote hedging words would have put 176 lines of prose out of\n   reach to keep two words of an example. That price is gone.\n\n   **A shown directive has to be inline or fenced, never a bare line.**\n   A directive on a line of its own now takes effect on the recipe at\n   any indent, and the CLI strips it before serving so a reader never\n   sees it. Measured: a directive inside backticks and a directive\n   inside a fenced block are both inert, which is why every directive\n   quoted in this file is one or the other.\n\n   **Then the fields the extension point adds**. This is where the rule\n   actually lives, and each check reads only its own:\n\n| extends          | its fields                                                                   |\n|------------------|------------------------------------------------------------------------------|\n| `existence`      | `tokens` (a list) or `raw`; `ignorecase`, `nonword`, `exceptions`, `append`, `vocab` |\n| `substitution`   | `swap` (a map of observed → expected); `ignorecase`, `nonword`, `exceptions`, `capitalize`, `pos`, `vocab` |\n| `capitalization` | `match`; `style` (with `$title`), `exceptions`, `threshold`, `indicators`, `prefix`, `vocab` |\n| `occurrence`     | `token`, `max` and/or `min`; `ignorecase`                                    |\n| `repetition`     | `tokens`; `alpha`, `ignorecase`, `exceptions`, `max`, `vocab`                |\n| `consistency`    | `either` (a map of the two acceptable forms); `ignorecase`, `nonword`        |\n| `conditional`    | `first`, `second`; `exceptions`, `ignorecase`, `vocab`                       |\n| `metric`         | `formula`, `condition`                                                       |\n| `readability`    | `metrics` (a list of formula names), `grade`                                 |\n| `spelling`       | `aff`, `dic`, `custom`, `filters`, `ignore`, `threshold`                     |\n| `sequence`       | `tokens` (each a `pattern`/`tag` map); `ignorecase`, `exceptions`             |\n| `script`         | `script` (Tengo source)                                                      |\n\n   The list above is measured, not transcribed: every entry was added to\n   a minimal rule of that check and the run watched for `E201`. Three\n   corrections fall out of it, all against the published docs:\n   `capitalization` takes `prefix` (singular) and rejects both `prefixes`\n   and `suffixes`, it rejects `ignorecase`, and `occurrence` rejects\n   `exceptions` and `vocab`.\n\n   **Field names are matched case-insensitively, but `extends`, `message`\n   and `level` are not.** Measured: `Tokens:` and `ignoreCase:` are read\n   exactly as their lowercase spellings, while `EXTENDS:` fails with\n   "Missing the required \'extends\' key". Their *values* are case-sensitive\n   too, `level: WARNING` and `extends: Existence` are both rejected.\n   Write everything lowercase and none of this can bite you.\n\n   **A field from the wrong check is the loudest failure Vale has.**\n   `tokens` on an `occurrence` check gives\n   `E201 … has invalid keys: \'tokens\'`, exit 2, and, because Vale reads\n   one assembled config per run. **no** Vale rule in the project reports\n   anything. `verify` rejects the rule before Vale is invoked, so this\n   cannot reach `check`.\n\n   **Two checks are exempt, and that is not a licence.** Measured,\n   `consistency` and `spelling` accept any key at all: `bananafield:\n   true` on either loads without complaint and is ignored. A misspelled\n   field on those two is a silent no-op instead of a loud one, so the\n   schema cannot catch a typo there and neither can Vale. Read the field\n   list twice when writing those two.\n\n   **What `%%s` fills with depends on the extension point.** Getting this\n   wrong is the one mistake in this recipe that passes every check below\n. The rule fires, the fixtures are green, and only a human reading the\n   message sees that it is nonsense.\n\n| extends          | `%%s` count | fills with, left to right                             |\n|------------------|-------------|-------------------------------------------------------|\n| `existence`      | one         | the matched text                                      |\n| `substitution`   | **two**     | the **replacement**, then the matched text            |\n| `capitalization` | one         | the scope that failed (the whole heading or sentence) |\n\n   Measured: a `substitution` message with a single `%%s` interpolates the\n   *replacement*, not the match, so `"Use GitHub not %%s"` against the text\n   `Github` renders `Use GitHub not GitHub`.\n\n   For the other nine, do not guess. Write the message, run step 6, and\n   read it back off the finding, no test you can write catches a wrong\n   `%%s`, so your own eyes on the rendered message are the check.\n\n   ```yaml\n   # existence, flag these tokens wherever they appear\n   extends: existence\n   message: "Avoid \'%%s\', it hides the work from the reader"\n   level: warning\n   ignorecase: true\n   tokens:\n     - simply\n     - just\n   ```\n\n   ```yaml\n   # substitution, first %%s is the replacement, second is what was found\n   extends: substitution\n   message: "Use \'%%s\' instead of \'%%s\'"\n   level: warning\n   ignorecase: true\n   swap:\n     utilize: use\n     "in order to": to\n   ```\n\n   ```yaml\n   # capitalization, a whole heading must be in sentence case\n   extends: capitalization\n   message: "\'%%s\' should be in sentence case"\n   level: warning\n   scope: heading\n   match: $sentence\n   exceptions:\n     - Taskless\n     - API\n   ```\n\n   `match` takes `$sentence`, `$title`, `$lower`, or `$upper`. A literal\n   string is legal but means "this whole scope must read exactly that",\n   which is almost never what anyone wants. See step 1.\n\n   **`$sentence` means first word capitalized, everything else lowercase\n, proper nouns included.** It is not "sentence case allowing proper\n   nouns". Measured with `exceptions: [Taskless, API]` on headings:\n\n| Heading                           | Result                                         |\n|-----------------------------------|------------------------------------------------|\n| `Getting started with the API`    | quiet                                          |\n| `Getting started with APIs`       | quiet, an exception covers its plural         |\n| `Taskless and the API`            | quiet, an exception may lead the scope        |\n| `Getting started with Kubernetes` | **fires**: a proper noun you did not list     |\n| `getting started lowercase`       | **fires**: the first word must be capitalized |\n| `Getting Started With Title Case` | **fires**                                      |\n\n   So `exceptions` is not decoration: every proper noun, product name and\n   acronym the docs use has to be listed, or the rule flags correct\n   headings. Collect them from the docs before writing the rule, and\n   expect to add to the list.\n\n3. **Know what you are writing: `tokens` and `swap` keys are patterns,\n   not literals.** They compile as **Go RE2** regular expressions.\n\n   *This step is about `tokens` and `swap` only. A `capitalization`,\n   `occurrence` or `metric` rule has neither, skip to step 4.*\n\n   - `(?:…)`, `[…]`, `|`, `+`, `?` all work.\n   - **Lookahead and lookbehind do not exist in RE2.** A rule that needs\n     "X but not when followed by Y" cannot be written as a single\n     `substitution`; split it or narrow with `scope`.\n   - **Word boundaries are applied for you, around the whole pattern.**\n     Measured: `Github` does not fire inside `GithubToken`, and the\n     multi-word `click here` does not fire inside `Clicking here`.\n   - **A hyphen is a boundary, so a hyphenated compound is not\n     protected.** `obviously` fires inside `obviously-named`, while\n     `obviously_stale` is safe because `_` is a word character. Do not\n     reach for a hyphenated compound as a `pass/` near-miss; it is the\n     case most likely to fire.\n   - **Regex metacharacters in a real phrase are live.** "maybe?" is a\n     pattern meaning "mayb" followed by an optional "e". Escape it.\n   - **Overlapping alternatives resolve first-wins**, one finding per\n     match. If `can login` and `login with` both match a sentence, you\n     get whichever is written first, once, not both.\n   - `ignorecase: true` matches any casing **and still skips text that\n     already equals the replacement.** Measured with `Github: GitHub`:\n     `github` and `Github` are flagged, `GitHub` is not. You do not need\n     `ignorecase: false` to protect the correct spelling.\n   - `raw` takes a full regex when `tokens` is too restrictive;\n     `nonword` removes the implicit boundaries.\n   - **A token made only of punctuation can never match without\n     `nonword: true`.** The boundaries above are `\\b`, which needs a word\n     character on the inside. An em dash has none, on either side.\n     Measured against `This is a sentence, with an em dash.`:\n\n     ```yaml\n     # fires on nothing, ever, and reports no error\n     extends: existence\n     message: "Use a comma, not an em dash"\n     tokens:\n       - \', \'\n     ```\n\n     ```yaml\n     # fires\n     extends: existence\n     message: "Use a comma, not an em dash"\n     nonword: true\n     tokens:\n       - \', \'\n     ```\n\n     The first rule verifies, tests green if its `fail/` fixture is\n     missing the dash, and reports nothing forever. Any token whose\n     pattern contains no `\\w` (punctuation, an emoji, a bare symbol)\n     needs `nonword: true`.\n\n   - **A bare word finds senses you did not mean.** `landed on` in a rule\n     <!-- vale no-hedging.no-hedging = NO -->\n     about jargon also matches "the plane landed on time"; `simply` in a\n     rule about hedging also matches "simply connected" in a maths doc.\n     <!-- vale no-hedging.no-hedging = YES -->\n     Narrow the token to the **collocation** you actually object to\n     (`landed on a decision`, not `landed on`), and check that you got it\n     right by writing the `pass/` fixture from the literal sense *first*:\n     put the innocent sentence in `pass/` before you write the guilty one\n     in `fail/`. A rule whose `pass/` bucket was written afterwards tends\n     to contain only sentences the author already knew were safe.\n\n   Vale also understands the markup, which decides what counts as text\n   before your pattern ever runs. Measured in markdown:\n\n   - **URLs and code spans are not prose.** A `Github` key fires on\n     `Plain Github here` and not on `https://Github.com/x` or\n     `` `Github/docs` ``.\n   - **Link text *is* prose.** In `[click here](https://example.com)`,\n     `click here` is matched. The URL is not. With no `scope`, a rule\n     fires on both link text and ordinary prose; `scope: link` narrows it\n     to link text alone. Measured: without a scope the token hit both the\n     link and the sentence; with `scope: link`, only the link.\n\n4. **Scope the rule** by writing `.taskless/rules/vale/<id>/.vale.ini`.\n   This is the step that is easy to skip and impossible to notice\n   skipping. A rule with no config is enabled nowhere: it parses, it\n   runs, and it reports nothing.\n\n   The whole file, for a rule that applies to markdown:\n\n   ```ini\n   # Which files this rule applies to.\n   [*.md]\n   tskl) rule = no-simply\n   BasedOnStyles =\n   no-simply.no-simply = YES\n   ```\n\n   Four lines, and each one earns its place:\n\n   - `[*.md]` is a **matcher**: a glob over paths, deciding which files\n     this rule sees. Match it to the files the rule is actually about,\n     such as `[*.{md,markdown}]` or `[docs/**/*.md]`. A rule can declare\n     several matchers if it needs to. Before you widen a glob, check the\n     reach table below, what Vale does to a file it cannot parse is not\n     "nothing".\n   - `tskl) rule = <id>` is a breadcrumb Taskless reads to attribute the\n     matcher back to this rule after assembly interleaves every rule\'s\n     matchers into one file. Vale parses the key and ignores it. Write it\n     in every matcher you add, or the tooling loses track of who owns\n     what.\n   - `BasedOnStyles =` with an empty value says explicitly that no\n     bundled style loads. The default is already empty, so this changes\n     nothing today. Write it anyway: it tells the next reader that no\n     style is missing.\n   - `no-simply.no-simply = YES` turns the rule on. The first half is\n     the style, which is this rule\'s directory; the second is the check\n     inside it, which is the file. Both are the id.\n\n   **Scope a rule *out* with a second matcher, not a cleverer glob.** A\n   glob says which files a rule sees; it has no way to say "these but not\n   those". The exclusion is a second matcher that assigns `NO`, and\n   because precedence here is positional (a later matcher wins), the\n   exclusion goes **after** the inclusion:\n\n   ```ini\n   # Every markdown file…\n   [*.md]\n   tskl) rule = no-simply\n   BasedOnStyles =\n   no-simply.no-simply = YES\n\n   # …except the changelog, which quotes release notes verbatim.\n   [CHANGELOG.md]\n   tskl) rule = no-simply\n   no-simply.no-simply = NO\n   ```\n\n   Write the breadcrumb in the second matcher too, or assembly attributes\n   it to nobody. Reversing the two blocks silently re-enables the rule on\n   the file you meant to exempt, and nothing reports that.\n\n   **Do NOT write `StylesPath` or `MinAlertLevel` here.** Those describe\n   the run rather than a rule, the assembler supplies them, and a copy\n   in a rule\'s config is dropped on the way in.\n\n   Keep assignments underneath a matcher. An assignment above the first\n   `[…]` line belongs to no matcher, and Vale ignores it after warning\n   on stderr.\n\n   **What a matcher\'s glob is allowed to catch.** Vale (v%(VALE_VERSION)s)\n   treats a file one of four ways, decided by extension. The lists are\n   rendered from the pinned Vale version, not written out here, so they\n   track the shipped binary.\n\n   - **markup**: the document is prose and the format\'s own non-prose\n     constructs are skipped. This is the tier every `scope:` value\n     assumes; `scope: heading` has nothing to find outside it:\n     %(VALE_MARKUP_FORMATS)s\n   - **comment text only**: the comments are linted and the code body\n     <!-- vale no-hedging.no-hedging = NO -->\n     is invisible, which is exactly right for "comments must not say\n     \'obviously\'":\n     <!-- vale no-hedging.no-hedging = YES -->\n     %(VALE_COMMENT_FORMATS)s\n   - **plaintext fallback**: everything else, `.yml` `.toml` `.sh`\n     `.sql` and every extension not named above included. There is no\n     parser, so the whole file is linted as prose: a rule matched to\n     YAML flags key names and values, not just the comments. If that is\n     not what the rule means, narrow the glob rather than accepting it.\n     These land here despite reading like markup, so a `scope:` value\n     has nothing to act on in them: %(VALE_PLAINTEXT_FORMATS)s\n   - **not supported**: Vale parses these only by shelling out to an\n     external program, and this build does not support any format that\n     needs one:\n     %(VALE_CONVERTER_FORMATS)s\n\n     Do not tell the user to install the program. Taskless excludes these\n     files from the run whatever is installed, so that a repository\n     checks the same way on every machine; `.xml` could not work anyway,\n     since an XSLT stylesheet is specific to the document.\n\n   **A single unreadable file fails the whole Vale pass.** Vale exits 2\n   with an `E100` runtime error and abandons the run, `--no-exit` does\n   not suppress it, so every other Vale rule over every other file goes\n   unreported. `[*.{md,typ}]` is not a slightly wider `[*.md]`; it is a\n   matcher that takes `check` down the first time the repo grows a\n   `.typ` file. Never put one of those extensions in a glob.\n\n   **A single oversized file is excluded before Vale ever opens it, not\n   linted slowly.** Vale\'s cost is quadratic in one file\'s size, so a\n   large enough document can consume the whole run\'s time budget on its\n   own and cost every other file its findings: the same failure mode as\n   the unreadable-file case above, from a different cause. `check`\n   preempts it: a target file over 128KB is skipped **only if some\n   matcher\'s own section would actually reach it**. The scan asks the\n   assembled config\'s own section patterns, the same ones you write in\n   this file\'s `.vale.ini`, rather than walking every file in the\n   project. A large lockfile or a generated file no rule\'s glob names is\n   left alone entirely, not merely reported softly: naming a file no\n   matcher was ever going to check would be a false positive, not a\n   caught coverage hole. A file that IS excluded is named in a `notices`\n   entry rather than a finding: unlike the unreadable-file case above,\n   where Vale\'s own error proves the file was a real target, this is a\n   preemptive guess from a filesystem walk, and a soft advisory fits an\n   unconfirmed guess better than a hard error does. A rule\'s own\n   fixtures are never this large in practice, so this should not surface\n   while authoring one. It matters when a matcher\'s glob is broad, such as\n   `[*.md]` or `[**/README.md]` at the project root, where a generated\n   changelog or an exported note can cross it.\n\n   That example changed with Vale v3.18.0, which is the point: the\n   dangerous extension is whichever one the list above says needs a\n   program, not the one you remember. `.mdx` was the example until that\n   release parsed it natively, and `.typ` took its place.\n\n   **`.mdx` is supported** as of Vale v3.18.0, which parses it natively\n   rather than shelling out. `[*.{md,mdx}]` is a legitimate matcher\n   again, the example this recipe used to warn about is no longer the\n   broken one. Check the lists above rather than reaching for that\n   memory: `.typ` moved the opposite way in the same release, so a\n   matcher covering Typst is now the one that takes the run down.\n\n   **In `.mdx`, a component\'s children are prose as of v3.19.0.** Vale\n   reads a JSX element\'s children as the Markdown they are, so text\n   inside a wrapping component (`<Steps>`, `<Tabs>`, `<Aside>`) is\n   linted at its own source position. Only tags, attributes, `{...}`\n   expressions, self-closing elements, and an element opened and closed\n   on one standalone line are still treated as code.\n\n   Two consequences for a rule you write against MDX. Coverage grew,\n   so a rule can now fire in prose it never reached before, which is a\n   finding count that moves without the rule changing. And the children\n   carry the element\'s name as a class scope, exactly as MyST and\n   Quarto directives do, so `scope: text.class.Aside` targets one\n   component\'s content. That is an open family: `verify` accepts any\n   `text.class.<name>` tail, because the set of component names is the\n   author\'s, not Vale\'s.\n\n5. **Write the fixtures.** Two directories inside the rule, both flat.\n   Vale lints the whole fixture tree, so a document nested a level\n   deeper would be linted and never checked against either bucket, which\n   `test` rejects by name rather than skipping. Keep both one level\n   deep:\n\n   ```\n   .taskless/rules/vale/<id>/.tests/pass/ok.md    # rule must stay quiet\n   .taskless/rules/vale/<id>/.tests/fail/bad.md   # rule must fire\n   ```\n\n   **The leading dot on `.tests/` is required.** ast-grep walks the\n   rules tree and parses every `.yml` it reaches as a rule, and a plain\n   `tests/` directory fails that scan for the whole project. A\n   dot-directory is skipped. Do not rename it.\n\n   Give the fixtures an extension your matcher\'s glob matches. A `.txt`\n   fixture under a `[*.md]` matcher is never linted, so the `fail/`\n   document silently passes.\n\n   **The `pass/` bucket is not "correct prose".** Correct prose proves\n   nothing. The rule was never going to fire on it. Fill it with the\n   near-misses that would catch an over-broad pattern. What counts as a\n   near-miss depends on the rule\'s shape:\n\n   - **`tokens`/`swap` rules**: the noun form you are not flagging, the\n     word inside a longer word, the term in a URL or a code span, the\n     correct spelling itself.\n   - **`scope`d rules**: the same phrase *outside* the scope. A rule\n     with `scope: link` needs the phrase in ordinary prose; a rule with\n     `scope: heading` needs it in body text. Without that, nothing proves\n     the scope is doing anything.\n   - **`capitalization` rules**: a scope that is entirely exceptions, a\n     scope whose exception word comes first, and the plural of an\n     exception.\n\n   That is the half of the fixture set that has to work for you.\n\n   **When the rule\'s subject normally appears in code, the `fail/`\n   fixture must carry it three ways**, inline in a code span, inside a\n   fenced block, and in ordinary prose, in that one document. A rule\n   about a command, a flag, a package name or an env var has a subject\n   that lives in fenced blocks in every real README, and the default\n   scope cannot see fenced blocks at all. A `fail/` fixture written only\n   in prose therefore fires, goes green, and the rule then catches none\n   of the real violations. Measured on one document holding the token in\n   all three places: the default scope found one of three, `raw` found\n   three. If the fixture fires on the prose line and not on the other\n   two, the answer is `scope: raw`. See step 2 for what that costs.\n\n   **Fixtures run under a config that isolates this rule, so a green\n   `test` is not evidence the rule reaches any real file.** `test`\n   generates its own `.vale.ini` pointing at the fixture directory and\n   enabling only `<id>.<id>`; your rule\'s own matcher globs are not\n   consulted. So a glob of `packages/cli/src/**/*.ts` that matches\n   nothing in the repository still produces a rule that verifies, tests\n   green, and reports forever. The only check for that is a real\n   `check` over a real file:\n\n   ```\n   %(TASKLESS_CLI)s check <a real path the rule should flag> --json\n   ```\n\n   Do that once, on a file you have deliberately made violate the rule,\n   before you believe the rule works.\n\n6. **Verify, then test.** Two commands, both taking the rule\'s\n   directory as their argument, both run from the project root:\n\n   ```\n   %(TASKLESS_CLI)s verify .taskless/rules/vale/<id> --json\n   %(TASKLESS_CLI)s test   .taskless/rules/vale/<id> --json\n   ```\n\n   `verify` asks whether the rule is well-formed: the style file parses,\n   `extends` names one of the twelve checks, `message` is present, `level`\n   is one Vale accepts, every `scope` operand is one Vale honors, every\n   field belongs to the check the rule extends, and the config declares a\n   matcher that enables `<id>.<id>`. It does **not** need fixtures, so run\n   it as soon as the style file exists.\n\n   Those checks are measured against Vale v%(VALE_VERSION)s rather than\n   transcribed from its docs, and they run **before** Vale is invoked.\n   That ordering matters for two of them: an unknown `extends` and a\n   foreign field each fail the whole Vale run rather than just this rule,\n   so letting either reach the binary would take every other Vale rule\'s\n   findings down with it.\n\n   `test` runs the rule against both buckets. It runs `verify` first and\n   stops if that fails, so a malformed rule tells you what is malformed\n   instead of complaining about fixtures.\n\n   Both report the same shape:\n\n   ```json\n   {"ok":true,"rules":[{"engine":"vale","ruleId":"no-simply",\n    "ok":true,"errors":[],"ran":true}]}\n   ```\n\n   `ok` is the answer. `errors` names what failed, one string per\n   problem. Exit code is 0 when every rule passed and 1 otherwise, so\n   both are safe to script.\n\n   Pass a directory above a rule and every rule beneath it is checked,\n   reported one entry per rule. `.taskless/rules/vale` covers every Vale\n   rule; no argument at all covers the project.\n\n   If you would rather see the raw findings, the message text and the\n   line numbers, run `check` against a bucket instead:\n\n   ```\n   %(TASKLESS_CLI)s check .taskless/rules/vale/<id>/.tests/fail --json\n   ```\n\n   Read `results` there. Ignore `success` and the exit code: `success`\n   says the run worked rather than that the fixture behaved, and the\n   exit code follows severity, so a `level: error` rule exits 1 on\n   `fail/` while a `warning` rule exits 0 and both are correct. `test`\n   answers pass-or-fail; `check` shows you the finding.\n\n   When a `fail/` document does not fire, work down this list before\n   touching the pattern. The cause is usually further up:\n   - Does the rule have a `.vale.ini` at all?\n   - Is the assignment underneath a `[…]` matcher?\n   - Is it spelled `<id>.<id>`, both halves the same?\n   - Does the matcher\'s glob match the fixture\'s extension?\n   - Only then: does the pattern actually match the text?\n\n   A `pass/` document that fires means the pattern is too broad. Look\n   for a missing word boundary, an unescaped metacharacter, or a swap\n   key that also matches the form you meant to allow.\n\n7. **Report.** Show the rule directory you created and what is in it, a\n   one-line summary of what the rule flags, and the glob it is scoped\n   to. The scope is a decision the user should see rather than one\n   buried in a config. Note that a whole-project `%(TASKLESS_CLI)s check` skips\n   your fixtures: `.taskless/` is excluded from the project walk, by\n   design. `test` is what exercises them.\n\n## Worked rules\n\nNine rules that work, each paired with the near-miss that fails. Every\none was run against the bundled Vale; the "what goes wrong" lines are\nobserved behavior, not warnings in principle. Find the entry closest to\nyour intent and start there.\n\n### 1. Ban a word or phrase, `existence`\n\n> "Our docs shouldn\'t hedge."\n\n```yaml\nextends: existence\nmessage: "Avoid hedging: \'%%s\'"\nlevel: warning\nignorecase: true\ntokens:\n  - we think\n  - it seems\n  - sort of\n```\n\n**Goes wrong:** dropping `ignorecase: true` when you meant any casing.\n`We think` at the start of a sentence then sails through. And a phrase\nwith punctuation is a *pattern*: `maybe?` means "mayb" plus an optional\n"e", so it matches `mayb`. Escape it: `maybe\\?`.\n\n### 2. Prefer one term over another, `substitution`\n\n> "Say \'sign in\', not \'login\', when it\'s a verb."\n\n```yaml\nextends: substitution\nmessage: "Use \'%%s\' instead of \'%%s\'"\nlevel: warning\nignorecase: true\nswap:\n  \'login (?:to|into)\': sign in to\n  \'to login\': to sign in\n```\n\n**Goes wrong:** one `%%s` instead of two. Measured, `"Use sign in not\n%%s"` against `login to` renders **"Use sign in not sign in to"**, the\nreplacement, twice. The rule fires, both fixtures pass, and only a human\nreading the message sees it. Two `%%s`, always, in that order.\n\n### 3. Enforce a product\'s spelling, `substitution`, not `capitalization`\n\n> "It\'s \'GitHub\', never \'Github\' or \'github\'."\n\n```yaml\nextends: substitution\nmessage: "Use \'%%s\' instead of \'%%s\'"\nlevel: error\nignorecase: true\nswap:\n  github: GitHub\n```\n\n**Goes wrong:** reaching for `capitalization` because the complaint is\nabout capitals. Measured, `match: GitHub` flags whole sentences:\n`\'We host on Github and it is fine. should be GitHub\'`, because that\ncheck tests a *scope*, not a word. Note also that `ignorecase: true` is\nsafe here: Vale skips text already equal to the replacement, so the\ncorrect `GitHub` is not flagged.\n\n### 4. Sentence-case headings, `capitalization`\n\n> "Headings are sentence case; our product names keep their capitals."\n\n```yaml\nextends: capitalization\nmessage: "\'%%s\' should be in sentence case"\nlevel: warning\nscope: heading\nmatch: $sentence\nexceptions:\n  - Taskless\n  - API\n  - Kubernetes\n```\n\n**Goes wrong:** a short `exceptions` list. `$sentence` lowercases\neverything after the first word, proper nouns included, so every product\nname and acronym in the docs must be listed or correct headings get\nflagged. Collect them from the docs first; expect to add more.\n\n### 5. Restrict a rule to link text, any check, plus `scope`\n\n> "\'click here\' is useless link text."\n\n```yaml\nextends: existence\nmessage: "Link text \'%%s\' says nothing, name the destination"\nlevel: warning\nscope: link\nignorecase: true\ntokens:\n  - click here\n  - read more\n```\n\n**Goes wrong:** omitting `scope: link`. Measured, the token then fires\non `[click here](…)` **and** on "click here to focus the search box" in\nordinary prose, which is a false positive on a sentence that is fine.\nWhenever a rule is about a *place* in the document, the `pass/` fixture\nmust contain the same phrase outside that place, otherwise nothing\nproves the scope works.\n\n### 6. Cap how often something appears, `occurrence`\n\n> "At most one exclamation mark per paragraph."\n\n```yaml\nextends: occurrence\nmessage: "Too many exclamation marks"\nlevel: warning\nscope: paragraph\ntoken: "!"\nmax: 1\n```\n\n**Goes wrong:** forgetting `scope`. The count is per scope, so with no\nscope you are capping the whole document rather than the paragraph.\nNote `token` here is singular, this check takes one, not a `tokens` list.\n\n### 7. Catch a doubled word, `repetition`\n\n> "\'the the\' keeps slipping through review."\n\n```yaml\nextends: repetition\nmessage: "\'%%s\' is repeated"\nlevel: warning\nalpha: true\ntokens:\n  - \'[^\\s]+\'\n```\n\n**Goes wrong:** leaving the pattern unquoted. Measured, an unquoted\n`[^\\s]+` in YAML silently matches nothing, zero findings, no error, no\ndiagnostic. Quote any pattern containing a backslash. This is the\nfailure mode this recipe warns about most, arriving through YAML rather\nthan through Vale.\n\n### 8. One spelling or the other, consistently, `consistency`\n\n> "Pick -ize or -ise and stick to it."\n\n```yaml\nextends: consistency\nmessage: "Use \'%%s\' consistently"\nlevel: warning\nnonword: true\neither:\n  organize: organise\n```\n\n**The id must be word characters only.** `consistency` is the one\nextension point that compiles the rule\'s own name into the pattern, as\na `(?P<id>…)` capture group, and Go RE2 rejects a group name containing\na hyphen. Measured: an id of `ize-ise` fails with `E201 … invalid group\nname` and takes **every** Vale rule in the project down with it, because\nVale reads one config for the whole run. Name this one `izeise` or\n`spelling_variants`. Kebab-case is right everywhere else.\n\n**Goes wrong:** expecting it to pick a winner. It flags the *second*\nform once both appear in a document, it enforces internal consistency,\nnot house style. If you want one specific spelling, that is a\n`substitution`.\n\n### 9. Require a definition, `conditional`\n\n> "An acronym must be spelled out before it\'s used."\n\n```yaml\nextends: conditional\nmessage: "\'%%s\' has no definition"\nlevel: warning\nscope: text\nignorecase: false\nfirst: \'\\b([A-Z]{3,5})\\b\'\nsecond: \'(?:\\b[A-Z][a-z]+ )+\\(([A-Z]{3,5})\\)\'\n```\n\n`first` is what must be justified; `second` is what justifies it.\nMeasured: `Application Programming Interface (API)` licenses every later\n`API`, while an undefined `XYZ` is flagged.\n\n**Goes wrong:** swapping the two, which inverts the rule into "flag the\ndefinition when the acronym is missing".\n\n## Important Notes\n\n- Vale reads one document at a time and has no cross-document view. A\n  rule about consistency *between* documents cannot be written here.\n- Prose inside code is still prose: comments and docstrings are Vale\'s\n  subject, and a rule about them belongs under a matcher whose glob\n  covers the source files.\n- Do NOT add a `[*]` matcher to widen a rule that isn\'t firing. Matchers\n  from every rule are assembled into one config, so `[*]` applies this\n  rule to every file the walk reaches and turns one rule\'s scoping bug\n  into a flood of false positives.\n\n## See Also\n\n- `%(TASKLESS_CLI)s agent route`: re-decide the destination\n- `%(TASKLESS_CLI)s agent check`: run every engine over the repo\n- `%(TASKLESS_CLI)s agent create-sg-rule`: author a rule over code structure\n', ne = `# Topic: delete-rule     (CLI v%(CLI_VERSION)s / topic v4)
+
+## Goal
+Remove a rule and its associated test files from \`.taskless/\`. Does not
+contact the Taskless API; purely a local filesystem operation.
+
+\`rule delete\` takes a bare id, not a path, and resolves which engine
+holds it: it searches \`.taskless/rules/sg/\`, \`vale/\` and \`runtime/\`.
+Deleting the directory by hand instead skips the metadata sidecar the
+CLI also removes, and skips the ambiguity check below.
+
+An id is not unique across engines. Nothing enforces uniqueness, so two
+engines can hold the same id, and the CLI refuses that case rather than
+picking one.
+
+## Preconditions
+- \`.taskless/\` directory exists.
+- The target rule directory exists under \`.taskless/rules/<engine>/<id>/\`
+  for exactly one engine.
+- No auth required.
+
+## Steps
+
+1. **Identify the rule.** If the user named one, use it. Otherwise,
+   list the engine directories under \`.taskless/rules/\` and ask which
+   rule. Confirm the user's intent, deletion is destructive.
+
+2. **Invoke the CLI.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s rule delete <id>
+   \`\`\`
+
+   The CLI removes:
+   - \`.taskless/rules/<engine>/<id>/\`: the whole directory, which holds
+     the rule, its \`.tests/\`, and any per-rule config
+   - \`.taskless/rule-metadata/<id>.yml\`, a sidecar the CLI never
+     writes. The removal is there for a directory a person created by
+     hand; expect it to be absent.
+
+3. **Report results.** Show the user what was deleted.
+
+## Errors
+
+When \`--json\` is set, failures emit \`{ ok: false, code, message }\` on
+stdout; on success the command exits 0 silently (no envelope).
+
+| code                | meaning                                | fix                                          |
+|---------------------|----------------------------------------|----------------------------------------------|
+| \`RULE_NOT_FOUND\`    | No engine holds that id                | Confirm the ID; list rules first             |
+| \`RULE_ID_AMBIGUOUS\` | Two engines hold it, so nothing was deleted | Remove the one you mean by path; the message names both |
+
+\`RULE_ID_AMBIGUOUS\` is not a retry. The id is well-formed and correct, and it
+matches more than one rule, so sending it again produces the same answer.
+Nothing is deleted when it is reported: the command refuses rather than picking
+one, because picking one removed a rule the caller may not have meant and
+reported success.
+
+The rule ID is required as a positional argument; citty rejects a
+missing ID before the command body runs, so \`INVALID_INPUT\` is not
+emitted from this command.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: make a new rule
+- \`%(TASKLESS_CLI)s agent check\`: run remaining rules to confirm nothing broke
+`, te = `# Topic: detect     (CLI v%(CLI_VERSION)s / topic v1)
+
+## Goal
+Scan the working directory for the linters it configures, the
+languages it uses, and the styles of any rules the repo already
+authors. Offline and deterministic, no network, no auth, no state
+change. This is the discovery step that feeds rule-authoring: the
+routing flow reads \`detect\` to decide where a new rule should live.
+
+## Preconditions
+- None. Works in any directory; doesn't require \`.taskless/\`.
+
+## Steps
+
+1. **Invoke the CLI** with JSON output:
+   \`\`\`
+   %(TASKLESS_CLI)s detect --json
+   \`\`\`
+
+2. **Parse the response.** Shape:
+   \`\`\`json
+   {
+     "success": true,
+     "linters": [
+       {
+         "name": "eslint",
+         "evidence": ["eslint.config.js", "dependency eslint (package.json)"]
+       }
+     ],
+     "languages": ["typescript", "javascript"],
+     "ruleStyles": [
+       {
+         "source": ".taskless/rules/sg",
+         "description": "ast-grep rules with YAML metadata sidecars"
+       }
+     ]
+   }
+   \`\`\`
+   - \`linters\`: each has a \`name\` and \`evidence\` (config-file paths,
+     a pyproject table marker, or a dependency marker from the
+     language's package file; not every entry is a path).
+   - \`languages\`: inferred from manifests and the detected linters.
+   - \`ruleStyles\`: how the repo authors its own rules, surfaced for
+     downstream reuse.
+
+3. **Use the signals to route.** Feed the output into rule authoring:
+   - A detected linter the repo already uses → author the rule there
+     (\`%(TASKLESS_CLI)s agent route\`).
+   - No suitable linter, local-only → \`%(TASKLESS_CLI)s agent create-sg-rule\`.
+   - See \`%(TASKLESS_CLI)s agent route\` for the full decision.
+
+## Errors
+
+When \`--json\` is set, failures emit \`{ ok: false, code, message }\`:
+
+| code             | meaning                    | fix                      |
+|------------------|----------------------------|--------------------------|
+| \`INTERNAL_ERROR\` | Internal schema validation | Report; likely a CLI bug |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: decide where to author a rule from these signals
+- \`%(TASKLESS_CLI)s agent check\`: run rules against the codebase
+`, se = `# Topic: feedback-invite     (CLI v%(CLI_VERSION)s / topic v1)
+
+## Before you finish: one question for the user
+
+Taskless would like to hear how this went. When the task above is done,
+and only then, put this to the user exactly once, in these words:
+
+> Taskless would like to know how the CLI is doing. Would you be okay
+> sharing a few sentences about your experience? Or just skip it with
+> \`skip\`.
+
+Then act on the reply:
+
+- **They gave feedback.** Fetch \`%(TASKLESS_CLI)s agent feedback\` and follow it.
+  It takes their words as they are and asks you, not them, for the rest.
+- **They said \`skip\`, said nothing, or replied about something else.**
+  That is a decline. Run:
+  \`\`\`
+  %(TASKLESS_CLI)s feedback dismiss
+  \`\`\`
+  and carry on with whatever they asked for. An unrelated reply is not
+  feedback, and it is not a reason to ask again.
+
+Ask once. Do not repeat the question later in this session, do not ask
+before the task is finished, and do not run \`feedback send\` without
+having asked.
+`, ae = `# Topic: feedback     (CLI v%(CLI_VERSION)s / topic v1)
+
+## You are here
+This is \`feedback\`. It helps you turn what a user just said about
+Taskless into a survey response the CLI can send, and send it.
+You reach it from the invite at the end of an authoring or onboarding
+recipe, after the user replied with something other than \`skip\`.
+If that is not why you are reading this, re-run \`%(TASKLESS_CLI)s agent\` and
+find the topic you meant.
+
+## Goal
+Produce one JSON payload that answers the survey, write it to
+\`.taskless/.tmp-feedback.json\`, send it with \`feedback send\`, and delete
+the file. The whole thing is one short exchange with the user and a few
+sentences from you; it is not an interview.
+
+## Preconditions
+- The user replied to the invite with feedback rather than \`skip\`,
+  silence, or something unrelated. If they did any of those, this is the
+  wrong recipe: run \`%(TASKLESS_CLI)s feedback dismiss\` and continue with what
+  they asked for.
+- The agent can write a file and run a shell command.
+- No auth required.
+
+## You are the respondent
+
+The survey is addressed to you, the agent, not to the user. One answer is
+the user's words and you record them verbatim. The other four are your
+own account of the session you just ran: what they were trying to do,
+whether they got it, what went well, and what did not. You already know
+all of that. Do not put the survey's questions to the user one by one.
+
+## Steps
+
+1. **Take the user's reply as it is.** Whatever they wrote after the
+   invite is \`verbatim\`. Do not paraphrase, shorten, or tidy it. If they
+   wrote several messages, join them in order with a blank line between.
+
+2. **Ask one follow-up at most, and only if needed.** If the reply is
+   feedback but leaves you unable to fill \`completed\`, ask whether they
+   got what they came for. Otherwise ask nothing further; the invite
+   already asked for their time once.
+
+3. **Fill the rest from the session.**
+   - \`goal\`: what the user was trying to accomplish, in one or two of
+     your own sentences. Name the recipe you were following and the
+     rule or task it was for.
+   - \`completed\`: \`Yes\`, \`No\`, or \`Unknown\`. Success is binary here. A
+     rule that verifies and the user accepted is \`Yes\`; a rule the user
+     abandoned or that never verified is \`No\`; if the session ended
+     before you could tell, \`Unknown\`. There is no partial.
+   - \`workedWell\`: the steps of the interaction with Taskless that went
+     smoothly. Omit the key if nothing stands out.
+   - \`needsImprovement\`: the steps that cost time, needed a retry, or
+     that you had to work around. Be specific: name the command, the
+     field, or the message. Omit the key if nothing stands out.
+
+   Keep your own answers to a few sentences each. The people reading
+   them want the shape of the friction, not a transcript.
+
+4. **Write the payload** to \`.taskless/.tmp-feedback.json\`, matching the
+   input schema below. Use the human keys exactly as given; the CLI maps
+   them to the survey's own question identifiers, and a payload carrying
+   a \`$survey_\` key is not what it expects.
+
+5. **Send.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s feedback send --from .taskless/.tmp-feedback.json --json
+   \`\`\`
+   Under \`--json\`, a failure is \`{ ok: false, code, message }\`; see the
+   table below. On success the command prints a thank-you.
+
+6. **Clean up.** Delete \`.taskless/.tmp-feedback.json\` whether the call
+   succeeded or failed. \`.taskless/.gitignore\` already ignores it, so a
+   forgotten file is a stray rather than a commit, but leave nothing
+   behind.
+
+7. **Return to the user's task.** Thank them in one line and carry on.
+   Do not ask for more, and do not run this recipe a second time in the
+   same session.
+
+## Input schema
+
+The \`--from\` JSON file conforms to:
+
+\`\`\`json
+%(INPUT_SCHEMA)s
+\`\`\`
+
+\`verbatim\`, \`goal\`, and \`completed\` are required. \`workedWell\` and
+\`needsImprovement\` are optional, and an optional answer you have nothing
+for is an omitted key rather than an empty string.
+
+## Important Notes
+
+- Do NOT edit the user's words. \`verbatim\` is the one answer that is
+  theirs, and its value to the people reading it is that it is theirs.
+- Do NOT invent a follow-up interview. The invite asked once; step 2 is
+  the only question this recipe allows, and only when \`completed\` would
+  otherwise be a guess.
+- If telemetry is disabled in this environment the command says so and
+  exits 0 with nothing sent. That is the expected outcome there, not an
+  error to retry.
+
+## Errors
+
+With \`--json\`, failures emit \`{ ok: false, code, message }\`:
+
+| code            | meaning                                     | fix                                                   |
+|-----------------|---------------------------------------------|-------------------------------------------------------|
+| \`INVALID_INPUT\` | \`--from\` missing, unreadable, or failed validation | the message names the field; fix the payload and retry |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s feedback dismiss\`: what to run when the user declined
+- \`%(TASKLESS_CLI)s agent\`: the topic index, if you arrived here by mistake
+`, oe = `# Topic: improve-rule (anonymous)     (CLI v%(CLI_VERSION)s / topic v2)
+
+## Goal
+Iterate on an existing ast-grep rule **locally** without contacting
+the Taskless API. You (the agent) edit the rule YAML directly, then
+validate with \`verify\` and \`test\` in a feedback loop.
+
+## Preconditions
+- \`.taskless/\` directory exists and contains the target rule.
+- The agent can read/write files and run shell commands.
+- No auth required.
+
+## Steps
+
+1. **Identify the target rule.** If the user named one, use it.
+   Otherwise, list \`.taskless/rules/sg/\` and ask which one. Read the
+   rule file and any test file under
+   \`.taskless/rules/sg/<id>/.tests/\`.
+
+2. **Gather improvement guidance.** Ask:
+   - Are there false positives (cases currently flagged but
+     shouldn't be)? Get concrete examples.
+   - Are there false negatives (cases passing but should be
+     caught)? Get concrete examples.
+   - Should the message, severity, or note change?
+
+3. **Plan the change.** Decide whether to:
+   - Tighten the \`rule\` (add \`inside\`, \`not\`, more specific \`kind\`)
+   - Loosen the \`rule\` (relax constraints, add \`any\` alternatives)
+   - Add \`ignores\` patterns for files/paths to skip
+   - Adjust \`message\`/\`severity\`/\`note\`
+   Summarize the planned change before editing.
+
+4. **Edit the rule file.** Make the change directly in
+   \`.taskless/rules/sg/<id>/<id>.yml\`. Preserve the existing \`id\`,
+   \`language\`, and \`severity\` unless the user explicitly asked to
+   change them.
+
+5. **Update test cases.** Add the new false-positive examples to the
+   \`valid:\` list and the new false-negative examples to the
+   \`invalid:\` list in \`.taskless/rules/sg/<id>/.tests/<id>-*.yml\`.
+
+6. **Run the verify feedback loop.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s test .taskless/rules/sg/<id> --json
+   \`\`\`
+   - If \`success: true\`: report success.
+   - If \`success: false\`: read the per-layer errors, fix, re-run.
+     Repeat up to 3 times. After 3 failed attempts, report to the
+     user with the latest errors and ask for guidance.
+
+   Common fixes:
+   - New tests fail → the rule still doesn't catch the case;
+     refine the pattern.
+   - Old tests broke → the new rule is too aggressive; add an
+     \`ignores\` clause or constrain \`kind\`.
+   - Schema errors → the YAML structure drifted; check fields.
+
+7. **Report results.** Show:
+   - The updated rule file path
+   - The updated test file path
+   - A diff-style summary of what changed
+   Suggest fetching \`%(TASKLESS_CLI)s agent check\` to validate against the
+   broader codebase.
+
+## Important Notes
+
+- Rules created in anonymous mode have no metadata sidecar: that's
+  fine. This recipe doesn't need or write metadata.
+- If the rule was originally created via the API path (has metadata),
+  you can still use this anonymous recipe to iterate locally. The
+  metadata sidecar is preserved untouched.
+- Do NOT make any HTTP requests to taskless.io.
+
+## Errors
+
+The verify primitive returns structured errors per layer:
+
+| layer          | what failure means                 | fix                                   |
+|----------------|------------------------------------|---------------------------------------|
+| \`schema\`       | YAML doesn't match ast-grep schema | Fix rule structure                    |
+| \`requirements\` | Missing Taskless-required field    | Add \`id\`/\`language\`/\`severity\`/etc.   |
+| \`tests\`        | A test case behaved unexpectedly   | Fix the rule pattern OR the test case |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent improve-rule\`: API-backed flow (auth required)
+- \`%(TASKLESS_CLI)s agent create-sg-rule\`: make a new rule locally
+- \`%(TASKLESS_CLI)s agent check\`: validate the updated rule
+`, ie = `# Topic: improve-rule     (CLI v%(CLI_VERSION)s / topic v5)
+
+## Goal
+Iterate on an existing Taskless rule. The CLI submits the user's
+guidance to the Taskless API iterate endpoint, which returns an
+updated rule that overwrites the original on disk. The agent's job
+is to gather the right ruleId + guidance + supporting references and
+to report the result.
+
+If the user wants the local-only flow (no API call), fetch
+\`%(TASKLESS_CLI)s agent improve-rule --anonymous\` instead.
+
+## Preconditions
+- User is logged in.
+- The project has a GitHub owner. Improvement runs through the same
+  service path as generation, so it carries the same constraint. Check
+  \`ghOwner\` from \`%(TASKLESS_CLI)s info --json\`: if it is the literal
+  \`[unknown]\`, stop and say the tier is unavailable rather than
+  submitting. \`auth login\` does not fix it, no GitHub owner is a
+  property of the project, not the session.
+- The target rule exists at \`.taskless/rules/sg/<id>/<id>.yml\`.
+- You have the rule's **ticket id**: the value \`%(TASKLESS_CLI)s rule
+  create --json\` printed as \`ruleId\` when the rule was generated. The
+  iterate endpoint is addressed by that id. Nothing on disk holds it,
+  so it comes from the create output or from the user. Without it,
+  fetch the anonymous variant instead.
+
+## Steps
+
+1. **Confirm auth.** Run \`%(TASKLESS_CLI)s info --json\` and check
+   \`loggedIn\`. If false, fetch \`%(TASKLESS_CLI)s agent auth\`.
+
+2. **Identify the rule to improve.** If the user named one, use it.
+   Otherwise, list rules in \`.taskless/rules/sg/\` and ask which one.
+   Read the existing rule file so you can summarize what it does.
+
+3. **Get the ticket id.** This is the id the iterate endpoint is
+   addressed by, and it is the \`ruleId\` field from that rule's
+   \`%(TASKLESS_CLI)s rule create --json\` output. Take it from the
+   session that created the rule, or ask the user for it.
+
+   **Do not run \`%(TASKLESS_CLI)s rule meta <id>\` to get it.** That
+   command reads \`.taskless/rule-metadata/<id>.yml\`, a sidecar this CLI
+   never writes, so it exits 1 with \`RULE_META_UNAVAILABLE\` for every
+   rule. If no one has the ticket id, fetch
+   \`%(TASKLESS_CLI)s agent improve-rule --anonymous\` and iterate
+   locally.
+
+4. **Gather improvement guidance.** Ask the user what should change:
+   - Are there false positives we need to exclude?
+   - Are there missed cases we need to catch?
+   - Is the message confusing or misleading?
+   - Should the severity change?
+
+   **"It doesn't fire on X" is often the \`$$$\` separator, not a pattern
+   that is merely too narrow.** Read the rule's pattern for a \`$$$\`
+   sitting next to a comma before you write that guidance. The comma is
+   itself an AST node that has to match, so \`f($A, $$$)\` never sees a
+   one-argument call and \`f($$$, $A)\` sees only one-argument calls, the
+   pattern reads as variadic and is not. \`%(TASKLESS_CLI)s agent create-sg-rule\`
+   carries the arity table and both remedies. Guidance that asks to
+   widen the rule when the fix is \`strictness: ast\` sends the iterate
+   endpoint after the wrong change, and it will oblige.
+
+5. **Collect supporting references.** Ask the user for any code
+   examples that should be:
+   - **Not flagged** (currently flagged but shouldn't be): false
+     positive references.
+   - **Flagged** (currently passing but should be caught): false
+     negative references.
+
+   Each reference is \`{ filename: string, content: string }\`. Multiple
+   references are an array.
+
+6. **Confirm the request.** Summarize the rule, the guidance, and
+   the references before submitting.
+
+7. **Write the JSON payload.** Build a JSON object matching the input
+   schema below and write it to \`.taskless/.tmp-improve-request.json\`.
+
+8. **Invoke the CLI.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s rule improve --from .taskless/.tmp-improve-request.json --json
+   \`\`\`
+   This may take 30-60 seconds while the API generates the update.
+
+9. **Clean up.** Delete \`.taskless/.tmp-improve-request.json\`
+   regardless of success or failure.
+
+10. **Report results.** The CLI overwrites the rule file (and its
+    test file) with the updated version. Show the file paths and a
+    summary of what changed. Suggest fetching \`%(TASKLESS_CLI)s agent check\`
+    to validate.
+
+    **Read \`notices\` if it is present.** It is an optional array of
+    advisory messages about a delivery that was written anyway. A rule
+    arriving with no \`.tests/\` fixtures is the one to expect. Surface any notice
+    rather than reporting an unqualified success. Under \`--json\` these
+    do not go to stderr, so the envelope is the only place they appear.
+
+    **Confirm both fixture buckets are still non-empty.** \`test\` fails
+    an ast-grep rule whose \`valid:\` or \`invalid:\` array is empty, and
+    narrowing a pattern to kill a false positive is exactly how
+    \`invalid:\` ends up with nothing the rule still matches. Run
+    \`\`\`
+    %(TASKLESS_CLI)s test .taskless/rules/sg/<id> --json
+    \`\`\`
+    on the returned files rather than trusting them, and add a fixture
+    the new pattern does match if that bucket came back empty.
+
+## Input schema
+
+The \`--from\` JSON file conforms to:
+
+\`\`\`json
+%(INPUT_SCHEMA)s
+\`\`\`
+
+\`ruleId\` is the original rule's ticket ID, printed as \`ruleId\` by
+\`%(TASKLESS_CLI)s rule create --json\`. It is not the YAML file name,
+and it is not readable from anything under \`.taskless/\`.
+
+## Errors
+
+When \`--json\` is set, failures emit \`{ ok: false, code, message }\`:
+
+| code                     | meaning                             | fix                                           |
+|--------------------------|-------------------------------------|-----------------------------------------------|
+| \`AUTH_REQUIRED\`          | not logged in                       | fetch \`%(TASKLESS_CLI)s agent auth\`           |
+| \`NO_GITHUB_REMOTE\`       | no GitHub origin remote             | retained for compatibility; treat as below    |
+| \`NOT_A_GIT_REPOSITORY\`   | not a git repository                | tell the user; \`auth login\` cannot fix it     |
+| \`NO_ORIGIN_REMOTE\`       | git repository, no \`origin\`         | tell the user; \`auth login\` cannot fix it     |
+| \`UNSUPPORTED_REMOTE_HOST\`| \`origin\` is not GitHub              | tell the user; \`auth login\` cannot fix it     |
+| \`INVALID_INPUT\`          | \`--from\` JSON failed validation     | re-read input schema, fix, retry              |
+| \`RULE_NOT_FOUND\`         | the service has no such ticket id   | re-check the id from \`rule create --json\`     |
+| \`NETWORK_ERROR\`          | API submit/poll failed              | report and suggest retry                      |
+| \`RULE_GENERATION_FAILED\` | API returned a generation failure   | report; suggest enriching guidance/references |
+| \`RULE_UNSUPPORTED\`       | plan lacks this generation type     | tell the user to enable it; do not retry      |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent improve-rule --anonymous\`: local-only flow
+- \`%(TASKLESS_CLI)s agent route\`: make a new rule from scratch
+- \`%(TASKLESS_CLI)s agent check\`: validate the updated rule
+`, re = `# Topic: info     (CLI v%(CLI_VERSION)s / topic v1)
+
+## Goal
+Report local Taskless state: CLI version, installed skill versions
+per detected tool, and (unless \`--anonymous\`) the user's auth state.
+Used as a health check, for staleness detection, and to confirm
+which version of the CLI/skills the agent is talking to.
+
+## Preconditions
+- None. Works in any directory; doesn't require \`.taskless/\`.
+
+## Steps
+
+1. **Invoke the CLI** with JSON output:
+   \`\`\`
+   %(TASKLESS_CLI)s info --json
+   \`\`\`
+   For an offline/local-only state report (no auth probe), pass
+   \`--anonymous\`:
+   \`\`\`
+   %(TASKLESS_CLI)s info --json --anonymous
+   \`\`\`
+
+2. **Parse the response.** Shape:
+   \`\`\`json
+   {
+     "success": true,
+     "version": "0.7.0",
+     "tools": [
+       {
+         "name": "Claude Code",
+         "skills": [
+           { "name": "taskless", "installedVersion": "0.7.0",
+             "currentVersion": "0.7.0", "current": true }
+         ]
+       }
+     ],
+     "loggedIn": true,
+     "auth": { "user": "...", "email": "...", "orgs": ["..."] }
+   }
+   \`\`\`
+
+3. **Report to the user.** Summarize:
+   - CLI version
+   - For each tool: number of installed skills, count out-of-date
+   - Auth: logged in as <user> (orgs) OR not logged in
+
+4. **Suggest reinit on staleness.** If any skill has \`current: false\`,
+   suggest \`%(TASKLESS_CLI)s\` to reinstall and pull the latest
+   bundle.
+
+## Errors
+
+When \`--json\` is set, failures emit \`{ ok: false, code, message }\`:
+
+| code             | meaning                    | fix                      |
+|------------------|----------------------------|--------------------------|
+| \`INTERNAL_ERROR\` | Internal schema validation | Report; likely a CLI bug |
+
+(Network errors during the auth probe are silently swallowed:
+\`info\` falls back to reporting \`loggedIn: false\` rather than
+failing.)
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent auth\`: log in / log out / status detail
+- \`%(TASKLESS_CLI)s agent check\`: run rules against the codebase
+`, le = `# Topic: init     (CLI v%(CLI_VERSION)s / topic v2)
+
+## Goal
+Install or update the Taskless skill in this project, and migrate the
+\`.taskless/\` layout when the project is behind the CLI. You most often
+arrive here because \`check\`, \`verify\`, or \`test\` refused with
+\`SCAFFOLD_MIGRATION_REQUIRED\`: those commands only read, so the rewrite
+is left to \`init\`, which is the one command that migrates.
+
+An install rewrites files under version control and can change what an
+upgrade means for the rules already in the project. Running the command
+is the first of three steps, not the whole job.
+
+## Preconditions
+- None at the project level. The command works in any directory and
+  bootstraps \`.taskless/\` on first run.
+- No auth. \`init\` never calls the Taskless API.
+- No TTY needed. \`init\` is the batch path in every context; the wizard
+  is only reached by running the CLI with no subcommand in a terminal.
+
+## Steps
+
+1. **Run the install.**
+   \`\`\`
+   %(TASKLESS_CLI)s init --json
+   \`\`\`
+   The envelope:
+   \`\`\`json
+   {
+     "success": true,
+     "commandsInstalled": true,
+     "cliVersion": { "previous": "0.10.2", "installed": "0.11.1" },
+     "targets": [
+       { "dir": ".taskless", "mode": "canonical",
+         "writtenSkills": ["taskless"], "writtenCommands": [],
+         "removedSkills": [], "removedCommands": [] },
+       { "dir": ".claude", "mode": "reference",
+         "writtenSkills": ["taskless"], "writtenCommands": ["tskl.md"],
+         "removedSkills": [], "removedCommands": [] }
+     ],
+     "changed": true,
+     "migrated": { "from": 3, "to": 4, "applied": [4],
+                   "files": { "added": [], "modified": [], "removed": [] } }
+   }
+   \`\`\`
+   - \`cliVersion.previous\` is \`null\` on a project with no recorded
+     install. When it differs from \`installed\`, the CLI was upgraded.
+   - \`targets\` lists every install location and what this run wrote or
+     removed there, by name. \`mode: "canonical"\` is the \`.taskless/\`
+     store; \`reference\` is a tool directory holding stubs.
+   - \`changed\` is \`true\` when a migration ran, any target list is
+     non-empty, or \`cliVersion\` moved (that rewrites
+     \`.taskless/taskless.json\`). When it is \`false\`, stop here: nothing
+     to commit, nothing to reconcile.
+   - \`migrated\` is present only when a migration ran, with the paths it
+     added, rewrote, or deleted.
+
+   Without \`--json\`, the same facts print as prose: a per-target summary,
+   then a trailer naming the directories that changed and, after a
+   version move, pointing at \`update\`.
+
+2. **Tell the user what needs committing.** Every \`targets[].dir\` with
+   a non-empty list, plus \`.taskless/\` and any \`migrated.files\` entries,
+   now holds changes that belong in version control. Name those paths and
+   say what Taskless rewrote and why (a CLI upgrade, a layout migration),
+   so the user can include them in the commit they choose. Do not stage
+   or commit on your own; the git operations are theirs.
+
+3. **After a version move, reconcile the rules.** When
+   \`cliVersion.previous\` is non-null and differs from \`installed\`, run
+   \`\`\`
+   %(TASKLESS_CLI)s update
+   \`\`\`
+   and follow it. The migration moved the DIRECTORY; the rules in it may
+   still need work an upgrade cannot do for them (a rewriter that now
+   needs a \`fix\`, a rule whose matching semantics shifted under a new
+   engine). \`update\` is how to find out, and the only way to record that
+   the walk was done.
+
+4. **Treat your own session as stale.** A tool loads its skill list once,
+   at startup. If Taskless was installed or upgraded during this session,
+   the skill text in your context is the previous version. Tell the user
+   the skills changed and that a new session, or a skill reload, picks
+   them up. Recipes are unaffected: every \`agent <topic>\` fetch reads the
+   installed CLI.
+
+5. **Return to what sent you here.** Re-run the command that refused.
+
+## For a person at a terminal
+
+\`%(TASKLESS_CLI)s\` with no subcommand launches an interactive wizard. It
+detects the installed tools (Claude Code, OpenCode, Cursor, Codex), asks
+which to enable, offers a login (skippable), shows a diff against the
+previous install, then writes the canonical \`taskless\` skill (and \`tskl\`
+command) once to \`.taskless/\` and a thin stub into each selected tool
+directory. Stale layouts from older installs converge to stubs
+automatically; v0.6-era per-task skills and commands are removed and the
+summary shows what went.
+
+## Errors
+
+- \`SCAFFOLD_VERSION_MISMATCH\`: the project's \`.taskless/\` is NEWER than
+  this CLI. Upgrade the CLI; do not migrate downward.
+- No tools detected → the skill is written to \`.agents/skills/\` and no
+  slash command is installed. Not an error.
+- Wizard cancelled (Ctrl-C) → no filesystem writes. Re-run when ready.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s update\`: what an upgrade changed for existing rules
+- \`%(TASKLESS_CLI)s agent info\`: verify what's installed and check staleness
+- \`%(TASKLESS_CLI)s agent auth\`: authenticate after installing
+`, he = `# Topic: onboard     (CLI v%(CLI_VERSION)s / topic v3)
+
+## Goal
+Help a user who has just installed Taskless go from zero rules to a
+useful starter set by mining their codebase, agent-memory files, PR
+review history, and issue tracker for high-signal rule candidates.
+This is a conversational discovery flow, not a script, the agent
+collaborates with the user on what to scan and surfaces hypothetical
+rules as a bullet list the user can choose to materialize via the
+\`rule create\` flow.
+
+## Preconditions
+- \`.taskless/\` directory exists (Taskless is installed). The
+  \`%(TASKLESS_CLI)s onboard\` subcommand bootstraps it on first run, so this
+  is automatically satisfied.
+- A working repository the agent can read.
+- No auth required to surface candidates. (Materializing a rule via
+  \`rule create\` may require auth. Fetch \`%(TASKLESS_CLI)s agent auth\` if
+  needed at that point.)
+- The criterion for where a rule belongs lives in
+  \`%(TASKLESS_CLI)s agent route\` and is not restated here. This recipe
+  reads it; it does not duplicate it.
+
+## Steps
+
+1. **Read the manifest first.** Run
+   \`%(TASKLESS_CLI)s info --json\` and check whether
+   \`.taskless/taskless.json\` reports \`install.onboarded: true\`. The
+   \`%(TASKLESS_CLI)s onboard\` subcommand has already gated on this for you,
+   but if the user is invoking the recipe directly via the skill,
+   confirm with the user before running a long discovery pass.
+
+2. **Learn the routing surface before you propose anything.** A
+   candidate this repository cannot express is not a candidate, and
+   you cannot tell which is which until you know two things:
+
+   \`\`\`
+   %(TASKLESS_CLI)s agent route
+   %(TASKLESS_CLI)s detect --json
+   \`\`\`
+
+   Read \`route\` for the destination criterion, which rules are
+   decided by one file's syntax tree, by a document's words, by a
+   tool the repo already runs, or by evidence outside the files.
+   Read \`detect --json\` for what this repository actually has:
+   \`linters\`, \`languages\`, and \`ruleStyles\`.
+
+   Do this before you synthesize the bullet list, not after.
+   Proposing first and routing afterwards is how a bullet list ends
+   up carrying candidates that nothing can enforce. You are not
+   choosing a destination command here. That happens per accepted
+   bullet when you offer materialization.
+
+3. **Open the conversation about sources.** Tell the user you can mine
+   several places for rule candidates and ask which ones they want to
+   include. Default sources you should always offer:
+
+   - **Codebase TODOs / FIXMEs**: search for \`TODO\`, \`FIXME\`, \`XXX\`,
+     and \`HACK\` comments. Many of these are latent rules ("don't do
+     this", "remove when X").
+   - **Agent-memory files**: read \`CLAUDE.md\`, \`AGENTS.md\`,
+     \`.cursorrules\`, \`.opencode/AGENTS.md\`, and similar agent-context
+     files for explicit rules and conventions stated in prose.
+   - **Recent PR review comments**: only if the \`gh\` CLI is
+     available. Probe with \`command -v gh\`. Suggest scanning the last
+     30 days of merged PRs for repeated reviewer feedback patterns.
+   - **Issue tracker tickets**: only if a relevant MCP is wired in
+     (Linear, Jira, GitHub issues via \`gh issue list\`, etc.). Use
+     whatever issue-tracker tools you have available.
+
+   Then explicitly ask: "Are there other places I should look, a
+   team wiki, an internal docs site, a specific design doc, a Slack
+   channel export?" The user often knows about sources you don't.
+
+4. **Probe tool availability before promising a scan.** For each
+   source the user picks, verify the tool exists before committing
+   to it. Don't tell the user "I'll scan PR comments" if \`gh\` isn't
+   installed, say "PR comments need the GitHub CLI, or equivalent; want me to skip
+   this or wait while you install these tools?"
+
+5. **Scan with high-signal filtering.** For each chosen source:
+
+   - **Filter for repeated patterns.** A reviewer comment that
+     appears across multiple PRs is a much stronger rule candidate
+     than a one-off nit.
+   - **Prefer comments that cite a doc or style guide.** "Per our
+     style guide, no direct DB calls in controllers" is a rule.
+     "looks good" is not.
+   - **Prefer merge-blocking feedback.** Comments that gated a PR
+     merge are higher-signal than passing remarks.
+   - **Filter out one-off nits and pure formatting.** Linters and
+     formatters already handle those; Taskless rules earn their
+     keep on semantic patterns.
+
+6. **Synthesize the bullet list.** Present findings as a single
+   bullet list the user can scan quickly. One bullet per
+   hypothetical rule, in this format:
+
+   \`\`\`
+   - <kebab-case-name> [<destination>]: <one-line description of what it would enforce>
+   \`\`\`
+
+   \`<destination>\` is the routing call you reached when you learned
+   the routing surface, one of
+   \`legacy\`, \`sg\`, \`vale\`, or \`runtime\`. Example:
+
+   \`\`\`
+   - no-direct-db-access [sg]: Prevent controllers from importing the DB module directly; route through the service layer.
+   - require-zod-validation [sg]: Flag API handlers that read request bodies without parsing them through a Zod schema first.
+   - comments-record-not-forecast [vale]: Flag comments that promise future work instead of recording what is true now.
+   - exports-must-be-used [runtime]: Flag exported symbols nothing in the repo imports.
+   \`\`\`
+
+   The annotation is provisional. It tells the user what kind of rule
+   this would be, and it is why an unroutable candidate never reaches
+   the list. \`route\` adjudicates for real at materialization time, and
+   may land somewhere else once it has the rule's full description.
+
+   Order the bullets by your judgment of impact (frequency in the
+   source × severity of the issue × ease of enforcement). Don't
+   inflate the list, three high-quality candidates beat ten
+   speculative ones.
+
+7. **Offer materialization per bullet.** For each bullet, ask
+   whether the user wants to turn it into a real Taskless rule. On
+   yes, follow the \`%(TASKLESS_CLI)s agent route\` recipe you already
+   fetched when you learned the routing surface, the user's accepted
+   bullet becomes the rule description input. Re-fetch it only if it
+   has fallen out of context.
+
+8. **Ask before marking onboarding complete.** When the user signals
+   they're done (they've materialized everything they want, or
+   they've said "that's enough for now"), explicitly ask: "Do you
+   want me to mark Taskless as onboarded? You won't be re-asked to
+   onboard until you pass \`--force\`." On explicit yes, and only
+   on explicit yes, run:
+
+   \`\`\`
+   %(TASKLESS_CLI)s onboard --mark-complete
+   \`\`\`
+
+   Do NOT mark onboarding complete on your own initiative. Do NOT
+   run \`--mark-complete\` if the user is ambiguous, says "maybe
+   later", or stops responding. The flag is consent-gated.
+
+## Errors
+
+| code                | meaning                                      | fix                                  |
+|---------------------|----------------------------------------------|--------------------------------------|
+| \`ALREADY_ONBOARDED\` | \`install.onboarded\` is true and no \`--force\` | suggest \`--force\` or skip onboarding |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent route\`: the destination criterion; read it
+  before proposing candidates, and follow it to materialize an accepted one
+- \`%(TASKLESS_CLI)s agent detect\`: what this repository already lints
+  and authors, which bounds what a candidate can be
+- \`%(TASKLESS_CLI)s agent check\`: validate newly created rules against the codebase
+- \`%(TASKLESS_CLI)s agent info\`: inspect the current \`.taskless/taskless.json\` state
+`, ce = `# Topic: route     (CLI v%(CLI_VERSION)s / topic v5)
+
+## Goal
+Turn "write me a rule that…" into one command to run. This is the front
+door for every rule-authoring request, and it makes one decision (which
+of five recipes authors this rule) from one reading of the evidence.
+
+That single decision covers both halves that used to be asked
+separately: whether the rule can be built here, and which engine can
+express it. They are answered from the same signals, so they are
+answered together.
+
+## Preconditions
+- A working repository the agent can read.
+- No auth required to route. Login state is an *input* to the decision,
+  not a requirement of making it.
+
+## Steps
+
+1. **Read the repository.** %(DETECT_EVIDENCE)s the configured linters, languages, and the repo's own
+   rule styles. It is deterministic and offline. Use it as ground truth
+   instead of guessing the repo's tooling. The scan is monorepo-aware, so
+   evidence may carry a sub-package path. The output shape:
+   \`\`\`json
+   {
+     "success": true,
+     "linters": [{ "name": "eslint", "evidence": ["packages/api/.eslintrc.json"] }],
+     "languages": ["JavaScript", "TypeScript"],
+     "ruleStyles": [
+       { "source": ".taskless/rules/sg", "description": "Existing Taskless ast-grep rules." }
+     ]
+   }
+   \`\`\`
+
+2. **Read the login state and the repository context.** %(LOGIN_EVIDENCE)s \`loggedIn\` and \`ghOwner\`. Do this now, not later: they change
+   which destinations exist, so classifying first means classifying
+   against a set that may be wrong.
+
+   \`ghOwner\` is the GitHub owner this project belongs to, or the literal
+   \`[unknown]\` when there is none to find: not a git repository, no
+   \`origin\` remote, an \`origin\` that is not GitHub, or no git installed.
+   Read it from this payload rather than running \`git\` yourself, so the
+   destinations you offer match what the CLI will actually allow.
+
+   Reading it is not the same as asking about it. Do **not** open by
+   offering service generation. At this point neither you nor the user
+   knows whether this is a two-line pattern or something local authoring
+   cannot express, so the question costs a turn and cannot be answered
+   well.
+
+3. **State the evidence before you name a destination.** Write one
+   sentence: *"to decide this, you must look at ___."* Then a short
+   rationale covering what \`detect\` showed, whether a linter the repo
+   already runs could express this, and what the rule needs to read.
+
+   Do this first, every time. Naming a destination and justifying it
+   afterwards is how prose-about-code ends up in \`sg\` and cross-file
+   questions end up in \`vale\`.
+
+4. **Match the evidence to a destination.** The comparison is made here
+   and only here. The destination recipes describe their own scope and
+   deliberately do not restate this table.
+
+| The rule is decided by…                                                                                                      | Destination                                  | Login      |
+|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|------------|
+| a tool the repo already runs, in that tool's dialect                                                                         | \`create-legacy-rule\`                         | no         |
+| **one file's syntax tree**: a call, an import, a JSX attribute, a type annotation                                           | \`create-sg-rule\`                             | no         |
+| **a document's words**: docs, README, comments, commit bodies                                                               | \`create-vale-rule\`                           | no         |
+| **more than one file, or something outside the files**: the repo graph, git metadata, build output, a resolved config chain | \`create-runtime-rule\` / \`create-remote-rule\` | see step 5 |
+
+   Sharpening the three engine rows, because most wrong answers are one
+   of these:
+
+   - **Relational correlation inside one file is still \`sg\`.** "A
+     \`useEffect\` whose dependency array omits a value used in its body"
+     is one file's tree. If exactly one file settles it, it is \`sg\`.
+   - **Prose about code is still prose.** "Comments must not say
+     'TBD'" is \`vale\`. The evidence is the words. "Every exported
+     function has a doc comment" is \`sg\`. The evidence is whether a node
+     exists above a declaration. Ask what you would have to *read* to
+     decide, not what the subject matter is.
+   - **Vale sees one document at a time.** "This term is spelled
+     consistently ACROSS the docs directory" is a graph question, so it
+     is runtime, even though it is entirely about prose.
+   - **Trust tier is not a destination.** \`sg\` and \`vale\` are both
+     static-tier: inert data, always run, no login, no reconcile, no
+     signing. Only runtime executes code. "Static vs runtime" is a
+     different axis from "which engine", and conflating them is what
+     makes a prose rule look like it needs an account.
+
+   **What each local engine can actually read.** Both lists are rendered
+   from the pinned engine versions rather than written out here, so they
+   cannot go stale against the binaries: if one looks wrong, an engine
+   was bumped and a vendor-contract test is already red.
+
+   - **ast-grep (v%(AST_GREP_VERSION)s) parses:** %(AST_GREP_LANGUAGES)s.
+
+     Those spellings are ast-grep's own and go into a rule's \`language:\`
+     field verbatim. Nothing local validates that field, the vendored
+     schema types it as a bare string with no enum, so the first thing
+     with an opinion is the binary. It accepts some off-list aliases
+     (\`C++\` and \`cpp\` both reach the Cpp parser), but a name it does not
+     know at all, like \`C#\` for \`CSharp\`, aborts config parsing and
+     takes every other rule's report down with it. Copy from the list.
+
+     **A GitHub Actions workflow is \`Yaml\`, and \`Yaml\` is on that list.**
+     A rule about \`.github/workflows/*.yml\` is an \`sg\` rule; sending it
+     to runtime spends a login on a check that builds here.
+
+     **\`Markdown\` is on that list, and it is narrower than the name
+     suggests.** tree-sitter-markdown splits its grammar in two, block
+     and inline, and ast-grep exposes only the block tree. Measured at
+     v%(AST_GREP_VERSION)s against a document holding a heading, a
+     subheading, a list, a fenced block and a link:
+
+     - *Block structure works.* \`document\`, \`section\`, \`atx_heading\`,
+       \`setext_heading\`, \`fenced_code_block\`, \`list_item\` and
+       \`paragraph\` all match, and headings discriminate by level:
+       \`# $T\` matches only the h1, \`## $T\` only the h2.
+     - *Everything inside a line does not.* A paragraph's contents are
+       one opaque \`inline\` node. There is no \`link\` node, no \`emphasis\`,
+       no \`strong_emphasis\`. \`kind: link\` does not quietly find nothing:
+       it is a config error (\`Kind 'link' is invalid\`) that exits 8 and
+       takes every other rule's report down with it, the same shape as
+       \`C#\` above. The quiet version is the pattern form, where
+       \`[$T]($U)\` parses, runs, and matches nothing forever.
+     - So "no bare URLs", "link text must not read 'click here'", "no
+       bold inside a heading" feel structural and are not \`sg\` rules.
+       The evidence is words inside a line, which is Vale's.
+
+     **Neither static engine counts, and neither sees absence.**
+     ast-grep fires once per match, \`not\` scopes to a node rather than
+     to a document, and there is no count assertion. "Every doc has an
+     h1" and "at most one h1" are runtime however structural they look.
+
+     **\`.md\` is the first extension both static engines claim, so do
+     not route it by extension.** \`sg\` answers "does this block-level
+     shape occur in this file"; Vale answers "do these words appear in
+     this file's prose". Fences, heading levels and list shape are \`sg\`.
+     The wording inside a heading, a list item or a link is Vale.
+
+   - **Vale (v%(VALE_VERSION)s) reads three tiers, and hard-fails on a fourth.**
+     The tier is decided by the file's extension:
+
+     - *markup*: the whole document is prose, and the format's own
+       non-prose constructs are skipped:
+       %(VALE_MARKUP_FORMATS)s
+     - *comments only*: the comment text is linted and the code body is
+       invisible:
+       %(VALE_COMMENT_FORMATS)s
+     - *plaintext fallback*: everything else, \`.yml\` \`.toml\` \`.sh\`
+       \`.sql\` and every unnamed extension included. There is no parser,
+       so the file is linted as one block of prose, and a Vale rule
+       scoped to YAML flags the code as readily as the comments. That is
+       rarely what was asked for. Say so before writing it. These read
+       like markup and are not: %(VALE_PLAINTEXT_FORMATS)s
+     - *not supported*: Vale parses these only by shelling out to an
+       external program, and this build does not support any format that
+       needs one:
+       %(VALE_CONVERTER_FORMATS)s
+
+       Installing the program does not change this. Taskless excludes
+       these files from the Vale run whatever is on the machine, so that
+       a repository checks the same way everywhere rather than depending
+       on what a given host happens to have available.
+
+       **One such file fails the entire Vale pass, not just that file.**
+       Vale exits 2 with an \`E100\` runtime error, \`--no-exit\` does not
+       suppress it, and every other Vale rule over every other file goes
+       unreported. A matcher written as \`[*.{md,typ}]\` is not a wider
+       \`[*.md]\`. It is a broken one.
+
+       **\`.mdx\` is supported** as of Vale v3.18.0, which parses it
+       natively. It needs no external program and belongs with the
+       other markup formats above. \`.typ\` moved the other way in the
+       same release: Typst now parses through \`typst2vast\`, so a Typst
+       file is excluded rather than read as prose the way it was
+       before. Both are measured, not assumed.
+
+       As of v3.19.0 an MDX component's children are read as Markdown
+       too, so prose wrapped in \`<Steps>\` or \`<Aside>\` is linted where
+       it previously was not. That widens what a Vale rule covers in
+       \`.mdx\`; it does not change which extensions are safe to match.
+
+   **A language on neither list does not route to runtime by default.**
+   Check \`create-legacy-rule\` first: the repo may already run a linter
+   that speaks it, and that linter's own dialect is a local destination
+   with no login. Escalate only once nothing local can see the evidence.
+
+   Worked examples:
+
+| Rule intent                                              | Evidence needed                           | Destination        |
+|----------------------------------------------------------|-------------------------------------------|--------------------|
+| No \`eval(...)\` anywhere                                  | one file's call expressions               | \`create-sg-rule\`   |
+| Actions workflows must pin actions to a SHA              | one workflow file's tree (\`Yaml\`)         | \`create-sg-rule\`   |
+| \`useEffect\` deps must include what the body reads        | one file's tree, correlated within it     | \`create-sg-rule\`   |
+| Don't write "TBD" or "coming soon" in docs               | a document's words                        | \`create-vale-rule\` |
+| Comments must not say "for now"                          | a document's words (comments are prose)   | \`create-vale-rule\` |
+| Headings use sentence case                               | a document's markup                       | \`create-vale-rule\` |
+| Every code fence declares a language                     | one \`.md\` file's block tree               | \`create-sg-rule\`   |
+| Docs must not use setext (\`===\`) headings                | one \`.md\` file's block tree               | \`create-sg-rule\`   |
+| Link text must not read "click here"                     | words inside a line (no inline tree)      | \`create-vale-rule\` |
+| Every doc has exactly one h1                             | a count over a document                   | runtime            |
+| Exported symbols must be used somewhere in the repo      | every file, correlated                    | runtime            |
+| Product name spelled the same across all docs            | many documents, compared                  | runtime            |
+| Files changed in the last release need a changelog entry | git metadata, not file contents           | runtime            |
+| Imports must resolve through the tsconfig path aliases   | config chain resolution, outside the file | runtime            |
+
+5. **Split the runtime row on login state.** Runtime rules execute code,
+   so they run only against a server-verified signature:
+   - **logged in** → \`create-remote-rule\`. Go there directly; no recipe
+     forwards to another.
+   - **logged out** → \`create-runtime-rule\`, which explains the gate.
+
+   With \`ghOwner\` of \`[unknown]\`, \`create-remote-rule\` is not reachable
+   at all: see step 6.
+
+6. **Drop remote generation when \`ghOwner\` is \`[unknown]\`.** Generation
+   runs against a verifiable org, which comes from a GitHub \`origin\`.
+   Without one the tier cannot complete, so it is not a destination and
+   must not be presented as one. Route to the local recipe the rule's
+   shape calls for, and if the rule is only expressible at runtime, go
+   to \`create-runtime-rule\`.
+
+   Say the tier is unavailable and why, in one line. A reader who is not
+   told will read the omission as an oversight and ask for it, which
+   costs a turn and ends where this step already is.
+
+   This is **not fixed by \`auth login\`**. It is a property of the
+   project, not the session, so do not send them there for it.
+
+   Everything else still works: local authoring, \`verify\`, \`test\` and
+   \`check\` need no remote of any kind.
+
+7. **Offer the service only where it is a genuine choice.** When the
+   rule is expressible locally, the user is logged in, **and** \`ghOwner\`
+   is not \`[unknown]\`, present both and let them pick: a local rule you
+   write and verify now, or a generation that costs against their plan.
+   Say which you would choose and why.
+
+   Not logged in, no GitHub owner, or not locally expressible are not
+   choices. Do not pose them as one.
+
+8. **Name the command.** Finish by telling the user, or running, the
+   exact fetch for the destination you chose:
+   \`\`\`
+   %(TASKLESS_CLI)s agent create-vale-rule
+   \`\`\`
+   A destination that is not a runnable command is a category, and a
+   category is not an answer.
+
+## When two destinations both fit
+
+- **A linter the repo already runs AND a local Taskless rule both fit** →
+  do not silently pick. Present both with trade-offs and let the user
+  choose.
+- **A rule that seems to need two engines is usually two rules.** Split
+  it and route each half, rather than forcing one engine to cover
+  evidence it cannot see.
+- **You genuinely cannot tell** → ask the user a clarifying question.
+  Uncertainty is a reason to ask; it is never a reason to spend a
+  generation.
+
+## Failure fallback (try-verify-escalate)
+
+If you committed to a local rule on reasonable confidence and it then
+fails against the user's cases:
+
+- Tell the user the local rule could not capture them.
+- State that generating via the service uses a generation and requires
+  login.
+- Call the service only after the user confirms. On yes, fetch
+  \`%(TASKLESS_CLI)s agent create-remote-rule\`.
+
+Never fall through silently from a failed local attempt to a service
+call. A developer who watches a local attempt fail reads it as a
+Taskless failure, so only attempt local when you reasonably believe it
+will work.
+
+## Important Notes
+
+- **Reason first, route second.** Do not name a destination before the
+  rationale in step 3 is written.
+- **What the code actually looks like outranks how the request was
+  phrased.** Where you can see the code or the diff, weigh the concrete
+  syntactic form present in the repository above the wording. The same
+  sentence routes to \`create-sg-rule\` when the repository contains a
+  form that correlates statically, and to runtime when the equivalent
+  check would have to normalize a captured value against a declaration
+  elsewhere.
+- **Engine reach and engine availability are two different questions.**
+  Step 4's lists say what each engine can *parse*; they say nothing
+  about whether the binary resolved on this host. A language on the list
+  is still unusable where the platform build is missing.
+- **When it stays ambiguous, choose an engine whose availability you can
+  assert, and say that is why.** There is no fixed fallback. \`sg\` and
+  \`vale\` both ship as platform binaries, so either can be the missing one
+  on an unsupported architecture or where an install was blocked;
+  server-side the constraint is different again. A named default is
+  wrong in whichever situation it failed to anticipate.
+- **Stay local when you reasonably can.** Reasonable confidence is
+  enough to commit to a local rule, the failure fallback backstops a
+  wrong-but-reasonable bet.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent create-legacy-rule\`: author in a linter the repo already uses
+- \`%(TASKLESS_CLI)s agent create-sg-rule\`: author a local ast-grep rule (no login)
+- \`%(TASKLESS_CLI)s agent create-vale-rule\`: author a local Vale rule (no login)
+- \`%(TASKLESS_CLI)s agent create-runtime-rule\`: the runtime tier, logged out
+- \`%(TASKLESS_CLI)s agent create-remote-rule\`: generate via the service (login)
+- \`%(TASKLESS_CLI)s agent check\`: run every engine over the repo
+`, de = `# Topic: rule-meta     (CLI v%(CLI_VERSION)s / topic v3)
+
+## Goal
+Report what \`%(TASKLESS_CLI)s rule meta\` does today, so no recipe and no
+agent builds a step on top of it.
+
+## The sidecar does not exist
+
+\`.taskless/rule-metadata/<id>.yml\` is written from the \`meta\` block of a
+rule status response. The rule service does not populate that block, so
+this CLI has never written a sidecar for any rule, under any tier, in
+any mode. \`rule meta <id>\` therefore has nothing to read and exits 1
+with \`RULE_META_UNAVAILABLE\` for every id, including ids whose rule is
+plainly on disk.
+
+That code exists to keep the two cases apart. \`RULE_NOT_FOUND\` invites a
+retry with a different id; there is no id that works.
+
+## What to do instead
+
+\`rule improve\` needs the ticket id, and that id comes from the machine
+that created the rule, not from disk:
+
+- \`%(TASKLESS_CLI)s rule create --json\` prints it as \`ruleId\` on
+  success. Record it when you create a rule you expect to iterate on.
+- If the id was not recorded, ask the user for it.
+- If nobody has it, iterate locally: fetch
+  \`%(TASKLESS_CLI)s agent improve-rule --anonymous\`.
+
+## Errors
+
+| code                    | meaning                                  | fix                                   |
+|-------------------------|------------------------------------------|---------------------------------------|
+| \`RULE_META_UNAVAILABLE\` | no sidecar exists, and none is written   | Use the ticket id from \`rule create\`  |
+| \`INVALID_INPUT\`         | a sidecar exists and is malformed         | Delete it; nothing here depends on it |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent improve-rule\`: how the ticket id is actually sourced
+`, ue = `# Topic: rule     (CLI v%(CLI_VERSION)s / topic v2)
+
+## Goal
+Umbrella for rule operations. Fetch the topic for the action you want.
+
+## Topics
+
+| Action             | Recipe                                                |
+|--------------------|-------------------------------------------------------|
+| Create a rule      | \`%(TASKLESS_CLI)s agent route\`                        |
+| Improve a rule     | \`%(TASKLESS_CLI)s agent improve-rule\`                 |
+| Delete a rule      | \`%(TASKLESS_CLI)s agent delete-rule\`                  |
+| Verify a rule      | \`%(TASKLESS_CLI)s agent verify-rule\` (agent-internal) |
+| Read rule metadata | \`%(TASKLESS_CLI)s agent rule-meta\`   (agent-internal) |
+
+\`rule meta\` reads a sidecar this CLI never writes, so it fails for every
+rule. Fetch \`rule-meta\` only to learn what to do instead. \`improve-rule\`
+takes the ticket id from \`rule create --json\`.
+
+\`route\` is the entry point for authoring: it reads the request and
+names the \`create-*-rule\` topic that fits, so you do not pick an engine
+yourself.
+
+For the local-only flow on improve, append \`--anonymous\`.
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent check\`: run all configured rules
+`, pe = `# Topic: update     (CLI v%(CLI_VERSION)s / topic v6)
+
+## You are here
+This is \`update\`. It tells you what an upgrade changed for the rules
+ALREADY IN THIS PROJECT, and what to do about them.
+
+It is not about installing. Running \`%(TASKLESS_CLI)s\` migrates the
+\`.taskless/\` layout and refreshes the installed skills on its own. That
+handles the DIRECTORY. This recipe handles the RULES, which no migration
+can rewrite for you: a rewriter that now needs a \`fix\`, a rule whose
+matching semantics shifted under a new engine, a rule that could now be
+expressed better with a newly supported language.
+
+An agent that has run a migration and watched it succeed will otherwise
+reasonably conclude the upgrade is done. It is not. The directory is
+migrated; the rules may still need work.
+
+## Goal
+Walk the ledger below from the version this project was last reconciled
+to, up to the installed CLI, doing what each section says. Then record
+that you finished.
+
+## Preconditions
+- \`.taskless/\` exists. If it does not, there are no rules to reconcile.
+- You can read \`.taskless/taskless.json\`.
+
+## Steps
+
+1. **Find where to start.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s info --json
+   \`\`\`
+   and read \`rules.reconciledTo\`, plus \`rules.engines.sg\` and
+   \`rules.engines.vale\` for the engine versions the rules were built
+   against.
+
+   **No \`rules.reconciledTo\` at all** means this project PREDATES the
+   ledger, so treat it as \`0.0.0\` and walk every section. It does not
+   mean the project is new: a project this CLI set up has the field
+   stamped at creation, so an absent marker is the one case where none
+   of the entries below have ever been applied.
+
+   \`rules.walk\` on that same payload is this decision already made:
+   \`{ "from": ..., "to": ... }\` when there is something to walk, and
+   \`null\` when there is not. Prefer it to re-deriving the boundary
+   yourself, so the offer and the enforcement cannot disagree.
+
+2. **Walk forward, in order.** Start at the section after
+   \`reconciledTo\` and continue to the installed version. Sections are
+   cumulative, never replaceable: a later one can depend on an earlier
+   one having run, so do not skip ahead to the newest.
+
+3. **Do the work each section names.** Each says what changed and what
+   it means for existing rules. A section that says there is nothing to
+   do means exactly that; it is a claim, not an oversight.
+
+4. **Record that you finished.** Run:
+   \`\`\`
+   %(TASKLESS_CLI)s update --rules
+   \`\`\`
+   Only after the walk is complete. There is no version to pass: the CLI
+   stamps its own, because the only sensible endpoint of a walk is the
+   version you are running.
+
+   A partial or abandoned walk must not be recorded. The next agent
+   starts from what you wrote and skips everything you did not do, and
+   it will look like there was nothing to do. Nothing can check this for
+   you: the CLI refuses to move the marker backwards, but it cannot tell
+   whether you read the sections.
+
+   This also records the engine versions the rules are now valid
+   against, which is what lets a later upgrade say what moved.
+
+## The ledger
+
+### Migrating to 0.11.x
+
+The vendored ast-grep moves from 0.41.0 to 0.45.2, and Vale from 3.18.0
+to 3.20.0. Nine things follow for existing rules.
+
+**Elixir stopped being linted as prose.** Vale 3.19.0 reads \`.ex\` and
+\`.exs\` through a real parser, so it now sees comments and \`@doc\`
+attributes and nothing else. On 3.18.0 those files had no parser and
+were linted whole, so a Vale rule matching \`[*.ex]\` fired on function
+names, atoms, and string literals as well as on comments.
+
+Those findings are gone, and nothing errors or warns. A rule that
+reported on Elixir code bodies now reports less, which is a drop you
+would otherwise notice only as a suspiciously clean run. If the rule was
+meant for prose, this is the behaviour you always wanted. If it was
+being used to catch something in the code itself, that is a job for an
+\`sg\` rule, and \`%(TASKLESS_CLI)s rule create\` will route it there.
+
+**MDX components' children are prose now, and new findings appear.**
+As of Vale 3.19.0 a JSX element's children are read as the Markdown
+they are, so a rule over \`.mdx\` covers prose inside a wrapping
+component such as \`<Steps>\` or \`<Aside>\` that it previously skipped.
+Those children also carry the component name as a \`text.class.<name>\`
+scope, which a rule can target.
+
+This is the opposite direction from Elixir: coverage grew, so a rule
+reports MORE than it did. Read the new findings as real, and narrow the
+rule's \`scope\` only if the component's prose was deliberately out of
+reach.
+
+**An exception zone that did nothing now takes effect, and findings
+disappear.** Vale 3.20.0 records the region each \`<!-- vale <id>.<id> =
+NO -->\` and \`= YES\` pair covers, and suppresses any alert located
+inside it. Through 3.19.0 an *inline* pair (at a list item's
+continuation indent, with no blank line between it and the prose it
+wraps) was read once per block, so the two halves cancelled out and the
+zone did nothing at all.
+
+So a marker already sitting in this project's documents was inert and
+is now live. Nothing errors: findings a document has reported for as
+long as the rule existed stop appearing, which reads as a rule that
+broke. Before treating a drop as a regression, look for the
+markers: \`git grep -n '<!-- vale'\`. Keep the zone if it was meant; if
+it was a half-finished experiment, delete the pair and the coverage
+comes back.
+
+**A \`raw\`-scoped rule can be exempted in a document now.** Directives
+reach \`raw\` rules as of 3.20.0. Before, they were applied to the parsed
+document only and a \`raw\` rule fired straight through every zone, so a
+rule about a shell command, a flag, or a package name could only be
+removed, never exempted case by case. A rule that was narrowed or
+abandoned for that reason is worth revisiting.
+
+One caveat comes with it: at \`raw\` scope the directive line is itself
+linted text, so a rule whose token appears in its own id reports a
+finding on the marker that silences it. Rename the rule, or scope it.
+
+**\`sequence\` accepts \`exceptions\`.** The field is new in 3.20.0 and
+purely additive: no existing rule changes behaviour, and a sequence
+rule that was over-firing on a known phrase can now carry it. Upstream
+also changed how a negated sequence token is satisfied at a sentence
+boundary. No shape we tried reproduced a difference between 3.19.0 and
+3.20.0, so there is nothing to do unless you see one.
+
+**A rewriter now requires \`fix\`.** \`SerializableRewriter.required\` goes
+from \`["rule","id"]\` to \`["id","fix","rule"]\`, so a \`rewriters:\` entry
+without a \`fix:\` is now rejected where it was accepted before.
+
+Run \`%(TASKLESS_CLI)s verify\` and it names the offending rewriter
+directly. It cannot be auto-fixed: \`fix\` is replacement text, which is
+authorial intent. A rewriter with no \`fix\` could never have done
+anything, so this surfaces a rule that was already dead rather than
+breaking one that worked.
+
+**Markdown is now a language, with a narrow shape.** \`language:
+Markdown\` parses. What it sees is the BLOCK tree only: \`document\`,
+\`section\`, \`atx_heading\`, \`setext_heading\`, \`fenced_code_block\`,
+\`list_item\`, \`paragraph\`. Everything inside a line collapses into one
+opaque \`inline\` node, so there is no \`link\`, no \`emphasis\`, no
+\`strong_emphasis\`.
+
+Two failure shapes, and they are opposites. \`kind: link\` is a HARD
+CONFIG ERROR: exit 8, \`Kind \\\`link\\\` is invalid\`, which aborts config
+parsing and takes every other rule's report down with it. A pattern like
+\`[$T]($U)\` is the quiet one: it parses, runs, exits 0, and matches
+nothing forever.
+
+So "no bare URLs" and "link text must not say click here" are not
+ast-grep rules even now. Use Vale, which reads prose, and note that Vale
+DOES see YAML frontmatter: with \`scope: raw\` it sees the keys too, and
+\`extends: occurrence\` with \`min: 1\` can require a field to be present.
+
+**\`sg run --lang\` accepts the alias spellings.** At 0.41.0 \`--lang C++\`
+was rejected while \`language: C++\` parsed. At 0.45.2 both are accepted.
+This affects the flag only, not a rule's \`language:\` field, so no rule
+file needs changing. It is recorded because the divergence used to be
+documented as a thing to work around.
+
+**Matching semantics moved, and a valid, unchanged rule can now match a
+DIFFERENT SET OF NODES with no error and no warning.** Two shapes are
+affected. Both were measured against the two binaries, so this section
+says what to do rather than what to watch for.
+
+**A rule was silently dead and now fires.** If a rule uses \`nthChild\`
+with an \`ofRule\` whose body binds a metavariable:
+
+\`\`\`
+nthChild:
+  position: 2
+  ofRule: { pattern: $S }
+\`\`\`
+
+then at 0.41.0 it matched **nothing**, because \`ofRule\` reused one
+environment across siblings: the first match committed \`$S\` and every
+later sibling failed the consistency check and went uncounted. It now
+counts correctly and reports.
+
+So the rule is not broken, it was inert, and the findings it produces on
+this version have never been seen. Run \`%(TASKLESS_CLI)s check\` and read
+them as new: they are real matches the rule was always meant to make,
+and they may be numerous on a codebase that has never been checked
+against it. Fixtures are no help here, since a rule that matched nothing
+passed the \`pass/\` side of its own tests.
+
+A rule whose \`ofRule\` used a non-binding matcher, \`kind:\` or \`regex:\`
+with no metavariable, is unaffected: only binding was broken.
+
+**A metavariable is now empty where it used to carry a value.** If a
+rule binds a metavariable inside a negated \`not\` and then references it
+in \`message\`, \`fix\`, or a constraint:
+
+\`\`\`
+follows:
+  not:
+    pattern: return $A
+  stopBy: end
+message: "found after $A"
+\`\`\`
+
+then at 0.41.0 \`$A\` rendered with a value leaked from the candidate the
+negation REJECTED. A \`not\` contributes no bindings by definition, since
+a successful negation means the inner rule did not match, so that value
+was never meaningful. It is now unbound and renders empty.
+
+This one will not change your finding counts. The match is identical:
+same file, same range, same rule. Only the rendered output differs, so
+grep your rules for a metavariable that appears both inside a \`not\` and
+in a \`message\` or \`fix\`. A \`fix\` in that shape has been writing the
+leaked text into people's files.
+
+**Root metavariables and comments** also changed upstream
+(ast-grep/ast-grep#2868), but no shape we tried reproduced a difference,
+including the TSX case that PR names. Nothing to do unless you see one.
+
+### Migrating to 0.11.2
+
+Vale moves from 3.20.0 to 3.21.0, and ast-grep from 0.45.2 to 0.45.3.
+Nothing installed migrates for ast-grep: its one user-visible change is
+that an inline \`ast-grep-ignore\` comment takes effect only as the
+comment's first alphabetic text, which the 0.45.3 changeset describes
+and no rule file carries. Six things follow for existing Vale rules,
+every one measured against both binaries; the last is behaviour a rule
+can now use, not a change to one it has.
+
+**A duplicated matcher now keeps its LAST assignment.** Where a rule's
+\`.vale.ini\` repeats a \`[glob]\` section, or repeats a key inside one,
+3.20.0 kept the first value and 3.21.0 keeps the last (upstream 1e4f6ed,
+"let the project's rule settings win"). Precedence across different
+matchers was already last-wins, so the two directions now agree, and the
+guidance to put a disable AFTER the enable it narrows is right for both
+shapes. A rule that relied on the old order is one whose second
+assignment was being ignored; it now takes effect, and the rule turns on
+or off where it did not before. \`git grep -c '^\\[' .taskless/rules/vale\`
+finds a config with more than one section per rule to read.
+
+**A \`metric\` rule's \`scope\` is honored.** Through 3.20.0 a \`metric\`
+measured the whole document whatever its \`scope\` said; 3.21.0 measures
+the blocks the scope names, and only an absent scope, or \`scope: text\`,
+still means the document. A \`metric\` with \`scope: sentence\` or
+\`scope: paragraph\` now reports per block, so its findings move, appear,
+or disappear. If the document-wide reading was what you wanted, delete
+the \`scope\`.
+
+**Notebooks are read cell by cell.** \`.ipynb\` had no parser, so a rule
+matching \`[*.ipynb]\` was linting the notebook's JSON: cell source,
+outputs, and metadata alike. 3.21.0 reads a Markdown cell as Markdown
+and a code cell as its kernel's comments, and reads raw cells and
+outputs not at all. Findings drop, and \`Line\` now points into the
+notebook file. Nothing warns; a suspiciously clean run over notebooks is
+this.
+
+**An unknown \`action\` name fails the run at load.** Measured on
+3.20.0, a rule carrying \`action: {name: bogus}\` loaded, and the run
+died only when that rule fired, as an \`E100\` with no file and no line.
+3.21.0 refuses it when the rule loads, as an \`E201\` naming the file, so
+a rule that has been carrying a bad action without ever matching now
+fails every check, not just the ones where it matched. \`verify\` rejects
+a name outside \`replace\`, \`remove\`, \`suggest\`, \`convert\`, \`edit\`, so run
+it: the rule is named directly.
+
+**\`BlockIgnores\` and \`TokenIgnores\` apply to HTML.** A rule's
+\`.vale.ini\` carrying either key under an \`[*.html]\` matcher was ignored
+through 3.20.0 and takes effect on 3.21.0. Findings inside the ignored
+region disappear.
+
+Upstream also says a \`sequence\` rule with a negated scope (\`~list\`,
+\`~code\`) reported every match twice (vale-cli/vale#1169). No shape we
+tried reproduced a difference between the two binaries, including the
+one that PR's own test uses, so it is recorded the way the ast-grep
+root-metavariable case is: nothing to do unless you see one.
+
+**\`scope: doc(<selector>)\` selects part of a document by CSS selector**,
+which a rule could not do before: \`text & doc(section:has(> h2:contains("Decision")))\`
+is the prose of one section, \`~doc(...)\` is everything outside it, and
+a \`metric\` scoped to \`doc(...)\` puts a word budget on that section
+alone. \`%(TASKLESS_CLI)s agent create-vale-rule\` has the shapes and the
+one trap (a leaf element on its own, \`doc(h2)\`, is inert; chain it).
+No existing rule changes; this is a reason to revisit one that was
+narrowed by hand.
+
+## Errors
+
+With \`--json\`, \`--rules\` failures emit \`{ ok: false, code, message }\`:
+
+| code            | meaning                                        | fix                                        |
+|-----------------|------------------------------------------------|--------------------------------------------|
+| \`INVALID_INPUT\` | no \`.taskless/\`, or an older CLI would rewind the marker | set the project up, or upgrade first |
+
+## See Also
+
+- \`%(TASKLESS_CLI)s agent check\`: run every engine over the repo
+- \`%(TASKLESS_CLI)s agent improve-rule\`: rewrite a rule the walk flagged
+- \`%(TASKLESS_CLI)s agent info\`: what is installed, and staleness
+`, me = '# Topic: verify-rule     (CLI v%(CLI_VERSION)s / topic v3)\n\n## Goal\nCheck that a rule is well-formed (`verify`), then run its tests\n(`test`). Both address rules **by path**, so one command works the same\nfor every engine. Primary consumer is the create/improve feedback loop,\nbut agents can call either directly.\n\n## Preconditions\n- The rule exists at `.taskless/rules/<engine>/<id>/`.\n- Tests are optional for `verify` and are what `test` runs.\n- No auth required.\n\n## The two commands\n\n```\n%(TASKLESS_CLI)s verify <path> --json\n%(TASKLESS_CLI)s test   <path> --json\n```\n\n`verify` asks whether the rule has the components its engine requires.\nIt never runs the rule against anything, so it works on a rule whose\ntests do not exist yet. That is the point of splitting the two: an\nagent part-way through authoring needs to know the rule itself is valid\nbefore it can write a meaningful test for it.\n\n`test` runs the rule\'s tests. **It runs `verify` first and stops on\nfailure**, so a rule that is both malformed and under-fixtured reports\nthe malformation. The fixture complaint is the less useful of the two\nand would otherwise bury the reason the rule could never have run.\n\nWhat each engine is checked for:\n\n| engine    | `verify` checks                                                                                                                      | `test` runs                                                |\n|-----------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|\n| `sg`      | ast-grep schema, plus `id`/`language`/`severity`/`message`/`rule`, and `regex` accompanied by `kind`                                 | the `valid`/`invalid` cases in `.tests/`                   |\n| `vale`    | style parses, `extends` and `message` present, `level` in vocabulary, and the rule\'s `.vale.ini` enables `<id>.<id>` under a matcher | the `.tests/pass/` and `.tests/fail/` buckets              |\n| `runtime` | `check.ts` present, at least one capture rule in `captures/`                                                                         | each directory under `.tests/pass/` and `.tests/fail/`, as the check\'s `root` |\n\nA runtime rule\'s fixtures execute its `check.ts`, so they run only under\nthe policy `check` already applies: an authenticated reconcile that\nreturns the rule\'s signature, or `--dangerously-run-scripts`. When\nneither holds, that rule prints `○` rather than a tick, names the reason\nand the flag, and is reported as `"ran": false` with a `refused` string\nsaying why. It is counted under "did not run" rather than among the\nrules tested, and on its own it does not fail the command.\n\nRead `ran` before `ok`. A runtime rule that did not run is not a rule\nthat passed, and treating the two alike is the defect this reporting\nexists to prevent.\n\n## What a path means\n\nThe path is a location under `.taskless/rules/`, and the `<engine>`\nsegment is what decides the engine. Nothing parses a rule file to work\nout who owns it, so the same id under two engines is never ambiguous.\n\n| Path                             | Scope                                               |\n|----------------------------------|-----------------------------------------------------|\n| `.taskless/rules/vale/no-simply` | that one rule                                       |\n| `.taskless/rules/vale`           | every Vale rule                                     |\n| `.taskless/rules`                | every rule (also the default when you pass no path) |\n\nA path outside `.taskless/rules/` is an error naming the path. So is a\npath inside it that holds no rule.\n\n## Output\n\nBoth commands answer in the same shape, one entry per rule:\n\n```json\n{\n  "ok": false,\n  "rules": [\n    {"engine":"sg","ruleId":"no-eval","ok":true,"errors":[]},\n    {"engine":"vale","ruleId":"no-simply","ok":false,\n     "errors":["no-simply/.vale.ini never enables no-simply.no-simply, so the rule is present but off."]}\n  ]\n}\n```\n\n- `ok` at the top is true only when every rule passed.\n- `errors` is one string per problem, written to be read by a person.\n- `test` adds `ran`, which is false when `verify` failed and the tests\n  never executed, and false for a runtime rule the execution policy\n  refused. The second case also carries `refused` with the reason, and\n  is the one where `ok` alone would mislead you.\n\nWithout `--json` the same information prints as a `✓`/`✗`/`○` line per\nrule with its errors indented beneath. `○` is a rule that did not run.\n\n## Exit codes\n\n- `0`: every rule in scope passed. An empty rules tree also exits 0: a\n  project that has not written a rule yet is an ordinary state, and\n  failing there would make `verify` unusable in CI on a fresh install.\n- `1`: any rule failed, or the path could not be resolved.\n\n## In a feedback loop\n\nRun `verify` as soon as the rule file exists, fix what it names, then\nwrite tests and run `test`. Cap at 3 attempts and report to the user if\nit still fails.\n\n## See Also\n\n- `%(TASKLESS_CLI)s agent create-sg-rule`: author an ast-grep rule\n- `%(TASKLESS_CLI)s agent create-vale-rule`: author a Vale rule\n- `%(TASKLESS_CLI)s agent improve-rule`: iterate on a rule that already exists\n';
+var A = {}, _;
+function ge() {
+  return _ || (_ = 1, (function(e) {
+    (function() {
+      var t = {
+        not_type: /[^T]/,
+        not_primitive: /[^v]/,
+        number: /[diefg]/,
+        numeric_arg: /[bcdiefguxX]/,
+        json: /[j]/,
+        text: /^[^\x25]+/,
+        modulo: /^\x25{2}/,
+        placeholder: /^\x25(?:([1-9]\d*)\$|\(([^)]+)\))?(\+)?(0|'[^$])?(-)?(\d+)?(?:\.(\d+))?([b-gijostTuvxX])/,
+        key: /^([a-z_][a-z_\d]*)/i,
+        key_access: /^\.([a-z_][a-z_\d]*)/i,
+        index_access: /^\[(\d+)\]/,
+        sign: /^[+-]/
+      };
+      function s(h) {
+        return l(k(h), arguments);
+      }
+      function o(h, u) {
+        return s.apply(null, [h].concat(u || []));
+      }
+      function l(h, u) {
+        var r = 1, w = h.length, n, p = "", d, c, a, b, S, T, I, y;
+        for (d = 0; d < w; d++)
+          if (typeof h[d] == "string")
+            p += h[d];
+          else if (typeof h[d] == "object") {
+            if (a = h[d], a.keys)
+              for (n = u[r], c = 0; c < a.keys.length; c++) {
+                if (n == null)
+                  throw new Error(s('[sprintf] Cannot access property "%s" of undefined value "%s"', a.keys[c], a.keys[c - 1]));
+                n = n[a.keys[c]];
+              }
+            else a.param_no ? n = u[a.param_no] : n = u[r++];
+            if (t.not_type.test(a.type) && t.not_primitive.test(a.type) && n instanceof Function && (n = n()), t.numeric_arg.test(a.type) && typeof n != "number" && isNaN(n))
+              throw new TypeError(s("[sprintf] expecting number but found %T", n));
+            switch (t.number.test(a.type) && (I = n >= 0), a.type) {
+              case "b":
+                n = parseInt(n, 10).toString(2);
+                break;
+              case "c":
+                n = String.fromCharCode(parseInt(n, 10));
+                break;
+              case "d":
+              case "i":
+                n = parseInt(n, 10);
+                break;
+              case "j":
+                n = JSON.stringify(n, null, a.width ? parseInt(a.width) : 0);
+                break;
+              case "e":
+                n = a.precision ? parseFloat(n).toExponential(a.precision) : parseFloat(n).toExponential();
+                break;
+              case "f":
+                n = a.precision ? parseFloat(n).toFixed(a.precision) : parseFloat(n);
+                break;
+              case "g":
+                n = a.precision ? String(Number(n.toPrecision(a.precision))) : parseFloat(n);
+                break;
+              case "o":
+                n = (parseInt(n, 10) >>> 0).toString(8);
+                break;
+              case "s":
+                n = String(n), n = a.precision ? n.substring(0, a.precision) : n;
+                break;
+              case "t":
+                n = String(!!n), n = a.precision ? n.substring(0, a.precision) : n;
+                break;
+              case "T":
+                n = Object.prototype.toString.call(n).slice(8, -1).toLowerCase(), n = a.precision ? n.substring(0, a.precision) : n;
+                break;
+              case "u":
+                n = parseInt(n, 10) >>> 0;
+                break;
+              case "v":
+                n = n.valueOf(), n = a.precision ? n.substring(0, a.precision) : n;
+                break;
+              case "x":
+                n = (parseInt(n, 10) >>> 0).toString(16);
+                break;
+              case "X":
+                n = (parseInt(n, 10) >>> 0).toString(16).toUpperCase();
+                break;
+            }
+            t.json.test(a.type) ? p += n : (t.number.test(a.type) && (!I || a.sign) ? (y = I ? "+" : "-", n = n.toString().replace(t.sign, "")) : y = "", S = a.pad_char ? a.pad_char === "0" ? "0" : a.pad_char.charAt(1) : " ", T = a.width - (y + n).length, b = a.width && T > 0 ? S.repeat(T) : "", p += a.align ? y + n + b : S === "0" ? y + b + n : b + y + n);
+          }
+        return p;
+      }
+      var g = /* @__PURE__ */ Object.create(null);
+      function k(h) {
+        if (g[h])
+          return g[h];
+        for (var u = h, r, w = [], n = 0; u; ) {
+          if ((r = t.text.exec(u)) !== null)
+            w.push(r[0]);
+          else if ((r = t.modulo.exec(u)) !== null)
+            w.push("%");
+          else if ((r = t.placeholder.exec(u)) !== null) {
+            if (r[2]) {
+              n |= 1;
+              var p = [], d = r[2], c = [];
+              if ((c = t.key.exec(d)) !== null)
+                for (p.push(c[1]); (d = d.substring(c[0].length)) !== ""; )
+                  if ((c = t.key_access.exec(d)) !== null)
+                    p.push(c[1]);
+                  else if ((c = t.index_access.exec(d)) !== null)
+                    p.push(c[1]);
+                  else
+                    throw new SyntaxError("[sprintf] failed to parse named argument key");
+              else
+                throw new SyntaxError("[sprintf] failed to parse named argument key");
+              r[2] = p;
+            } else
+              n |= 2;
+            if (n === 3)
+              throw new Error("[sprintf] mixing positional and named placeholders is not (yet) supported");
+            w.push(
+              {
+                placeholder: r[0],
+                param_no: r[1],
+                keys: r[2],
+                sign: r[3],
+                pad_char: r[4],
+                align: r[5],
+                width: r[6],
+                precision: r[7],
+                type: r[8]
+              }
+            );
+          } else
+            throw new SyntaxError("[sprintf] unexpected placeholder");
+          u = u.substring(r[0].length);
+        }
+        return g[h] = w;
+      }
+      e.sprintf = s, e.vsprintf = o, typeof window < "u" && (window.sprintf = s, window.vsprintf = o);
+    })();
+  })(A)), A;
+}
+var V = ge();
+const fe = f({
+  prompt: i().trim().min(1, "prompt must be a non-empty string").describe("Description of the rule to generate"),
+  successCases: m(i()).optional().describe("Examples of correct code that should pass the rule"),
+  failureCases: m(i()).optional().describe("Examples of incorrect code that should fail the rule")
+}), Je = f({
+  success: j(!0),
+  ruleId: i().describe("UUID of the generated rule job"),
+  rules: m(i()).describe("Rule IDs that were generated"),
+  files: m(i()).describe("File paths that were written"),
+  notices: m(i()).optional().describe(
+    "Advisory messages about a delivery that was still written — a rule delivered with no `.tests/` fixtures above all. Present only when there is something to say. A machine consumer cannot read stderr prose, so these are carried here rather than only printed"
+  )
+});
+f({
+  error: i().describe("Error message")
+});
+const we = f({
+  ruleId: i().trim().min(1, "ruleId must be a non-empty string").describe("ID of the rule to improve"),
+  guidance: i().trim().min(1, "guidance must be a non-empty string").describe("Feedback for iterating on the existing rule"),
+  references: m(
+    f({
+      filename: i().describe("File path relative to .taskless/"),
+      content: i().describe("File content")
+    })
+  ).optional().describe("Reference files to include as context")
+}), Qe = f({
+  success: j(!0),
+  requestId: i().describe("The request ID for polling status"),
+  rules: m(i()).describe("Rule IDs that were updated"),
+  files: m(i()).describe("File paths that were written"),
+  notices: m(i()).optional().describe(
+    "Advisory messages about a delivery that was still written — a rule delivered with no `.tests/` fixtures above all. Present only when there is something to say. A machine consumer cannot read stderr prose, so these are carried here rather than only printed"
+  )
+});
+f({
+  error: i().describe("Error message")
+});
+const Ze = "01a0b1a0-80fb-0000-5dc1-baa4ec44e619", en = [
+  {
+    key: "verbatim",
+    id: "5feff6a3-6768-4817-92d7-5ae3975c6baa",
+    question: "What was the user's comments verbatim?"
+  },
+  {
+    key: "goal",
+    id: "561e87f4-a1b7-4855-b728-29d19421f7e7",
+    question: "What was the user trying to accomplish?"
+  },
+  {
+    key: "completed",
+    id: "6ebdfabb-3575-49aa-857c-47b6bbfdebc8",
+    question: "Did the user successfully complete the task in your opinion?"
+  },
+  {
+    key: "workedWell",
+    id: "2316428e-dc3e-4c96-ae67-a6e8c66d7db5",
+    question: "What steps of the interaction with Taskless worked well?"
+  },
+  {
+    key: "needsImprovement",
+    id: "67bedbd9-ca70-4c1c-b1a6-6df830a453dd",
+    question: "What steps of the interaction with Taskless could use improvement?"
+  }
+], C = ["Yes", "No", "Unknown"], nn = /* @__PURE__ */ new Set([
+  "onboard",
+  "create-sg-rule",
+  "create-vale-rule",
+  "create-remote-rule"
+]), D = 1440 * 60 * 1e3, tn = 10 * D, sn = 20 * D, ye = f({
+  verbatim: i().trim().min(1, "verbatim must be the user's own words, non-empty").describe("The user's reply, in their own words, unedited"),
+  goal: i().trim().min(1, "goal must be a non-empty string").describe("What the user was trying to accomplish, in your words"),
+  completed: F(C, {
+    error: `completed must be one of ${C.map((e) => `"${e}"`).join(", ")}`
+  }).describe(
+    "Whether the user completed the task, in your opinion. Success is binary; use Unknown when you cannot tell"
+  ),
+  workedWell: i().trim().min(1, "workedWell, when present, must be non-empty").optional().describe("Steps of the interaction with Taskless that worked well"),
+  needsImprovement: i().trim().min(1, "needsImprovement, when present, must be non-empty").optional().describe(
+    "Steps of the interaction with Taskless that could use improvement"
+  )
+}), be = "0.45.3", P = [
+  "Bash",
+  "C",
+  "Cpp",
+  "CSharp",
+  "Css",
+  "Dart",
+  "Elixir",
+  "Go",
+  "Haskell",
+  "Hcl",
+  "Html",
+  "Java",
+  "JavaScript",
+  "Json",
+  "Kotlin",
+  "Lua",
+  "Markdown",
+  "Nix",
+  "Php",
+  "Python",
+  "Ruby",
+  "Rust",
+  "Scala",
+  "Solidity",
+  "Swift",
+  "Tsx",
+  "TypeScript",
+  "Yaml"
+], ve = {
+  "c++": "Cpp",
+  cc: "Cpp",
+  cs: "CSharp",
+  cxx: "Cpp",
+  ex: "Elixir",
+  golang: "Go",
+  hs: "Haskell",
+  js: "JavaScript",
+  jsx: "JavaScript",
+  kt: "Kotlin",
+  py: "Python",
+  rb: "Ruby",
+  rs: "Rust",
+  sol: "Solidity",
+  ts: "TypeScript",
+  yml: "Yaml"
+}, ke = new Map(
+  P.map((e) => [e.toLowerCase(), e])
+);
+function an(e) {
+  const t = e.toLowerCase();
+  return ke.get(t) ?? ve[t];
+}
+const on = {
+  TypeScript: "ts",
+  Tsx: "tsx"
+}, Se = "3.21.0", R = "converter:", G = {
+  // markup — parsed, the format's own constructs skipped
+  ".htm": "markup",
+  ".html": "markup",
+  ".ipynb": "markup",
+  ".markdown": "markup",
+  ".md": "markup",
+  ".mdx": "markup",
+  ".mdown": "markup",
+  ".myst": "markup",
+  ".org": "markup",
+  ".qmd": "markup",
+  ".rmd": "markup",
+  ".xhtml": "markup",
+  // comment text only — the code body is invisible
+  ".c": "comment",
+  ".c++": "comment",
+  ".bsh": "comment",
+  ".cc": "comment",
+  ".clj": "comment",
+  ".cpp": "comment",
+  ".cs": "comment",
+  ".css": "comment",
+  ".csx": "comment",
+  ".cxx": "comment",
+  ".ex": "comment",
+  ".exs": "comment",
+  ".go": "comment",
+  ".h": "comment",
+  ".h++": "comment",
+  ".hpp": "comment",
+  ".hs": "comment",
+  ".java": "comment",
+  ".jl": "comment",
+  ".js": "comment",
+  ".jsx": "comment",
+  ".less": "comment",
+  ".lua": "comment",
+  ".php": "comment",
+  ".pl": "comment",
+  ".pm": "comment",
+  ".pod": "comment",
+  ".proto": "comment",
+  ".ps1": "comment",
+  ".qdoc": "comment",
+  ".qml": "comment",
+  ".py": "comment",
+  ".py3": "comment",
+  ".pyw": "comment",
+  ".r": "comment",
+  ".R": "comment",
+  ".rb": "comment",
+  ".rs": "comment",
+  ".sass": "comment",
+  ".scss": "comment",
+  ".sbt": "comment",
+  ".scala": "comment",
+  ".swift": "comment",
+  ".ts": "comment",
+  ".tsx": "comment",
+  // plaintext, and surprising about it — these look parsed and are not
+  ".mkd": "plaintext",
+  ".mkdn": "plaintext",
+  ".tex": "plaintext",
+  // plaintext HERE, though Vale's own docs list it as comment-tier. Measured on
+  // the pinned 3.21.0 binary a bare non-comment line lints, which is the
+  // plaintext signature. `.qml` and `.scss` sat here for the same reason until
+  // 3.18.0 made the docs true for them; `.pyi` is the row where transcribing
+  // the docs would still ship the wrong tier — the case for probing rather than
+  // copying.
+  ".pyi": "plaintext",
+  // converter-dependent — Vale supports the format, we ship no converter
+  ".adoc": "converter:asciidoctor",
+  ".asc": "converter:asciidoctor",
+  ".asciidoc": "converter:asciidoctor",
+  ".dita": "converter:dita",
+  ".typ": "converter:typst2vast",
+  ".rest": "converter:rst2html",
+  ".rst": "converter:rst2html",
+  ".xml": "converter:xsltproc and an XSLT stylesheet"
+};
+function x(e) {
+  return Object.entries(G).filter(([, t]) => t === e).map(([t]) => t);
+}
+const Te = x("markup"), Ie = x("comment"), Ae = x("plaintext"), M = Object.fromEntries(
+  Object.entries(G).flatMap(
+    ([e, t]) => t.startsWith(R) ? [[e, t.slice(R.length)]] : []
+  )
+);
+function xe() {
+  const e = /* @__PURE__ */ new Map();
+  for (const [t, s] of Object.entries(
+    M
+  )) {
+    const o = e.get(s);
+    o === void 0 ? e.set(s, [t]) : o.push(t);
+  }
+  return [...e].map(([t, s]) => ({
+    converter: t,
+    extensions: s
+  }));
+}
+const Le = xe(), rn = Object.keys(M);
+function Ee() {
+  return P.join(", ");
+}
+function _e() {
+  return Te.join(", ");
+}
+function Ce() {
+  return Ie.join(", ");
+}
+function Re() {
+  return Ae.join(", ");
+}
+function Ne() {
+  return Le.map(
+    ({ extensions: e, converter: t }) => `${e.join("/")} (needs ${t})`
+  ).join(", ");
+}
+const Oe = /* @__PURE__ */ Object.assign({
+  "../agent/auth.md": Y,
+  "../agent/check.md": H,
+  "../agent/ci.md": B,
+  "../agent/create-legacy-rule.md": X,
+  "../agent/create-remote-rule.md": J,
+  "../agent/create-runtime-rule.md": Q,
+  "../agent/create-sg-rule.md": Z,
+  "../agent/create-vale-rule.md": ee,
+  "../agent/delete-rule.md": ne,
+  "../agent/detect.md": te,
+  "../agent/feedback-invite.md": se,
+  "../agent/feedback.md": ae,
+  "../agent/improve-rule.anonymous.md": oe,
+  "../agent/improve-rule.md": ie,
+  "../agent/info.md": re,
+  "../agent/init.md": le,
+  "../agent/onboard.md": he,
+  "../agent/route.md": ce,
+  "../agent/rule-meta.md": de,
+  "../agent/rule.md": ue,
+  "../agent/update.md": pe,
+  "../agent/verify-rule.md": me
+});
+function Ke() {
+  const e = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map();
+  for (const [s, o] of Object.entries(Oe)) {
+    const l = Fe(o), g = s.split("/").pop()?.replace(/\.md$/, "");
+    if (g)
+      if (g.endsWith(".anonymous")) {
+        const k = g.slice(0, -10);
+        t.set(k, l);
+      } else
+        e.set(g, l);
+  }
+  return { recipeMap: e, anonymousMap: t };
+}
+const { recipeMap: N, anonymousMap: je } = Ke(), Ve = {
+  "create-remote-rule": fe,
+  "improve-rule": we,
+  feedback: ye
+}, De = "<package-manager-dlx>", Pe = "<taskless-cli>", Ge = "The caller supplies this evidence, which names", Me = "The caller supplies";
+function O(e, t, s) {
+  return `Run:
+   \`\`\`
+   ${e} ${t}
+   \`\`\`
+   ${s}`;
+}
+function v(e) {
+  return e.invocation ?? Pe;
+}
+function qe(e, t, s = {}) {
+  const o = {
+    CLI_VERSION: "0.11.2",
+    // Engine reach, from the pinned engine versions rather than transcribed
+    // into a recipe. A recipe carrying these lists by hand would go stale on
+    // the next binary bump with nothing to catch it, and stale prose about
+    // what an engine can read is worse than the silence it replaced — an agent
+    // acts on it. `src/rules/capabilities.ts` is the single place a bump edits,
+    // and the two vendor-contract tests fail until it agrees with the binary.
+    AST_GREP_VERSION: be,
+    AST_GREP_LANGUAGES: Ee(),
+    VALE_VERSION: Se,
+    VALE_MARKUP_FORMATS: _e(),
+    VALE_COMMENT_FORMATS: Ce(),
+    VALE_PLAINTEXT_FORMATS: Re(),
+    VALE_CONVERTER_FORMATS: Ne(),
+    PACKAGE_MANAGER_DLX: s.packageManagerDlx ?? De,
+    // The two steps that gather evidence by running this CLI. Rendered as
+    // whole blocks rather than stripped afterwards, because the default must
+    // stay byte-identical to what `taskless agent route` has always printed
+    // and a post-strip cannot promise that.
+    DETECT_EVIDENCE: s.mechanics === !1 ? Ge : O(v(s), "detect --json", "This returns"),
+    LOGIN_EVIDENCE: s.mechanics === !1 ? Me : O(v(s), "info --json", "and note"),
+    // Three steps, in descending order of how much the resolver actually
+    // knows: the caller was told how the CLI was launched; the build is a
+    // nightly/dev/self that knows what it is; nobody knows, so ask the agent.
+    TASKLESS_CLI: v(s)
+  };
+  if (e.includes("%(INPUT_SCHEMA)s")) {
+    const l = Ve[t];
+    o.INPUT_SCHEMA = l ? JSON.stringify($(l), null, 2) : "(no input schema for this topic)";
+  }
+  return o;
+}
+function q(e) {
+  const t = /* @__PURE__ */ new Set(), s = new Proxy(
+    {},
+    {
+      get(o, l) {
+        return typeof l == "string" && t.add(l), "";
+      },
+      has() {
+        return !0;
+      }
+    }
+  );
+  return V.sprintf(e, s), [...t];
+}
+function Ue(e, t, s = {}) {
+  return U(e, t, s);
+}
+function U(e, t, s = {}) {
+  const o = V.sprintf(e, qe(e, t, s));
+  return s.header === !1 ? L(o) : s.directive === !0 ? We(o, v(s)) : o;
+}
+const W = "# Topic:";
+function K(e) {
+  return `Resolved by the CLI when you fetched it. Your next Taskless task, in this session or another, fetches it again with \`${e} agent <topic>\`; do not reuse this copy. If Taskless was installed or upgraded during this session, the skill in your context is stale until it is reloaded.`;
+}
+function We(e, t) {
+  if (!e.startsWith(W)) return e;
+  const s = e.indexOf(`
+`);
+  return s === -1 ? `${e}
+${K(t)}` : `${e.slice(0, s)}
+${K(t)}${e.slice(s)}`;
+}
+function L(e) {
+  if (!e.startsWith(W)) return e;
+  const t = e.indexOf(`
+
+`);
+  return t === -1 ? "" : e.slice(t + 2);
+}
+function ln(e, t = {}) {
+  const s = E(e, t);
+  if (s !== void 0)
+    return Ue(s, e, t);
+}
+function E(e, t) {
+  return t.anonymous ? je.get(e) ?? N.get(e) : N.get(e);
+}
+function hn(e, t = {}) {
+  const s = E(e, t);
+  if (s === void 0) return;
+  const o = s, l = t.header === !1 ? L(o) : o;
+  return {
+    text: l,
+    variables: q(l)
+  };
+}
+function cn(e, t = {}) {
+  const s = E(e, t);
+  if (s === void 0) return;
+  const o = s, l = t.header === !1 ? L(o) : o;
+  return {
+    text: U(o, e, t),
+    variables: q(l)
+  };
+}
+function Fe(e) {
+  return e.replaceAll(/^[ \t]*<!--\s*vale\b.*?-->[ \t]*\r?\n?/gm, "");
+}
+export {
+  be as A,
+  ze as P,
+  Ze as S,
+  rn as V,
+  cn as a,
+  hn as b,
+  Ye as c,
+  nn as d,
+  tn as e,
+  Be as f,
+  ln as g,
+  M as h,
+  Se as i,
+  ye as j,
+  sn as k,
+  en as l,
+  an as m,
+  Ee as n,
+  on as o,
+  we as p,
+  Qe as q,
+  He as r,
+  fe as s,
+  Je as t,
+  Xe as w
+};