@catalyst-cloud/cli 0.8.0 → 0.9.1

package/dist/write.js

@@ -149,12 +149,21 @@ export async function cmdWrite(args, ctx, deps = {}) {
             const title = flagString(args, "title");
             if (!teamKey || !title)
                 throw new UsageError("write create needs --team <key> and --title <text>");
+            let description = flagString(args, "description");
+            if (flagBool(args, "stdin")) {
+                if (description !== undefined)
+                    throw new UsageError("write create takes --description <text> or --stdin, not both");
+                description = (await (deps.readStdin ?? readStdin)()).trimEnd();
+                if (!description)
+                    throw new UsageError("write create --stdin read an empty description");
+            }
             const team = teamByKey(doc, teamKey);
             const labels = flagList(args, "label").map((n) => labelId(team, n));
             const priority = flagString(args, "priority") !== undefined ? flagInt(args, "priority", 0) : undefined;
             result = await postAgent(api, doc, "issue-create", {
                 teamId: team.id,
                 title,
+                ...(description ? { description } : {}),
                 ...(labels.length ? { labelIds: labels } : {}),
                 ...(priority !== undefined ? { priority } : {}),
                 ...(asUser ? { createAsUser: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "paths:check": "node scripts/vendor-paths.mjs --check"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.10.0"
+    "@catalyst-cloud/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.1 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.1 — written in this repository for customer tenants -->
 
 # Catalyst Linear
 
@@ -20,7 +20,7 @@ Run each with `--help` first; scripts are executed, never read.
 - `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]` — a comment as the app actor; a machine record takes `--bookkeeping`.
 - `node scripts/move.mjs <ticket> --slot <slot>` — a card move by slot (`--state-type backlog` parks).
 - `node scripts/label.mjs <ticket> --add <name> --remove <name>` — labels, resolved through the contract.
-- `node scripts/create-ticket.mjs --team <key> --title <text>` — a new ticket; cite its identifier only after it prints.
+- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]` — a new ticket; cite its identifier only after it prints.
 
 Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connected or the write was refused (budget spent, slot unmapped, label absent; the one line printed says which).
 

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -9,7 +9,7 @@ This reference restates the write mechanism. The live values it depends on — t
 | a comment, threaded or top-level | `node scripts/comment.mjs <ticket> --body <text> [--parent <commentId>] [--bookkeeping]` |
 | a card move | `node scripts/move.mjs <ticket> --slot <slot>` or `--state-type backlog` |
 | a label on or off | `node scripts/label.mjs <ticket> --add <name> --remove <name>` |
-| a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text>` |
+| a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> \| --stdin]` |
 | a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
 
 Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the personal key this machine connected with — so the write carries the person's identity for attribution, and an ask names them. No script composes a URL, and none needs a Linear credential of its own.
@@ -36,7 +36,7 @@ Two labels are a human's, not yours: the release label (which frees a ticket the
 
 ## A new ticket takes the team key
 
-`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
+`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. A ticket's body goes in `--description`, or on stdin with `--stdin` when it runs to several lines; a title with no body gives whoever picks the ticket up nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
 
 ## What is never offered
 

package/skills/catalyst-linear/scripts/create-ticket.mjs

@@ -2,14 +2,17 @@
 // create-ticket.mjs — file a new ticket on a team as the app actor. The team is named by its key;
 // the CLI resolves the team id from the contract. A decision for a human is NOT a ticket filed here:
 // that is an ask, raised through the what-needs-me skill so it carries options, a default and blocks.
+import { readFileSync } from "node:fs";
 import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
 
-const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
+const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin] [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
 
 Creates one ticket. Wraps: catalyst-skills write create. Spends one unit of the daily write budget.
 
   --team <key>          the team key (the prefix of its ticket identifiers)
   --title <text>        the ticket title
+  --description <text>  the ticket description, in markdown
+  --stdin               read the description from stdin instead (for a multi-line body)
   --label <name|id>     a label to apply (repeatable); Catalyst label names resolve via the contract
   --priority <0-4>      Linear priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low
   --as-user             create with the personal identity instead of the app actor (rare)
@@ -26,14 +29,22 @@ if (wantsHelp(argv)) {
   console.log(HELP);
   process.exit(0);
 }
-const { flags } = parseFlags(argv, { bool: ["as-user", "json"], value: ["team", "title", "priority"], repeat: ["label"] });
+const { flags } = parseFlags(argv, { bool: ["stdin", "as-user", "json"], value: ["team", "title", "description", "priority"], repeat: ["label"] });
 if (!flags.team || !flags.title) usage("create-ticket needs --team <key> and --title <text> (see --help)");
+if (flags.description && flags.stdin) usage("give --description or --stdin, not both");
 
 const args = ["write", "create", "--team", flags.team, "--title", flags.title, "--json"];
+if (flags.description) args.push("--description", flags.description);
+let stdin;
+if (flags.stdin) {
+  stdin = readFileSync(0, "utf8");
+  if (!stdin.trim()) usage("stdin was empty");
+  args.push("--stdin");
+}
 for (const l of flags.label ?? []) args.push("--label", l);
 if (flags.priority !== undefined) args.push("--priority", flags.priority);
 if (flags["as-user"]) args.push("--as-user");
-const r = runCli(args);
+const r = runCli(args, { stdin });
 exitOnFailure(r);
 relayStderr(r);
 const result = parseJson(r.stdout);

package/skills/catalyst-onboard/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.1 — written in this repository for customer tenants -->
 
 # Onboard me
 
@@ -20,6 +20,7 @@ Scripts are run, never read. Each prints `--help`.
 - `node scripts/where-am-i.mjs` — every part, each with the instrument that read it, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected; that is one of the states it reports.
 - `node scripts/where-am-i.mjs --next` — the same reading, reduced to the single next step.
 - `node scripts/where-am-i.mjs --json` — the same document for you to branch on.
+- `node scripts/local-sync.mjs` — optional local replica and event sync status. Run `node scripts/local-sync.mjs --start` only after the person chooses local sync; the script starts the supported writer and waits for a live heartbeat at the cloud cursor.
 
 Start every session with it, and run it again after every step the person completes. It is the only thing that decides where you are.
 
@@ -28,6 +29,7 @@ Start every session with it, and run it again after every step the person comple
 | when | read |
 | -- | -- |
 | walking the steps — what each one does, what to read back, when it is done | `references/the-one-path.md` |
+| the person chooses an optional local event and replica cache | `references/local-sync.md` |
 | anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
 | the next step is a browser page, or a page said it worked and you have to confirm it | `references/what-the-browser-owns.md` |
 | the person asks what Catalyst actually is, or how a ticket gets worked | the `how-catalyst-works` skill |
@@ -41,11 +43,12 @@ Start every session with it, and run it again after every step the person comple
 ## Rules
 
 - **One step, then stop.** Say what you are about to do, do it, show the real output, say what it means and what comes next. Never queue several steps into one message, and never move on from a step you did not watch finish.
+- **Local sync is opt-in.** API-backed skills work without it. Ask whether the person wants a local event and replica cache before running `local-sync.mjs --start`. A detached process starting is not evidence of freshness; only the script's verified current verdict is.
 - **Report what you observed, not what you expected.** Print the lines the command actually produced. "That worked" without the output it produced is the single easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step you reported.
 - **Each part by its own instrument.** Read the machine with the machine's instrument and the project with the project's, and label every finding with the part it belongs to. The script does this for you; keep it that way when you summarize.
 - **Not ready is a question about who, not a reason to retry.** When something reports not ready, name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop — re-running a local command cannot move a check that belongs to a tenant owner, an admin, or a browser page.
 - **Never invent a count or a list.** Every number and every name comes from what a command printed. If you want to tell them how many projects are mapped, read it off the script's output; do not carry one over from an earlier turn.
-- **Three steps belong to a browser and always will**: approving the login, connecting Linear, and installing the GitHub App. Hand over the page and say what you need back. Do not claim you did them.
+- **Provider consent belongs to the person in a browser.** This includes approving login, the tenant's Linear connection and GitHub App install, and the member's personal Linear and GitHub connections. Start personal Linear consent after tenant Linear is connected; start personal GitHub consent only after the tenant GitHub App is installed and its repository is registered. Give the person the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
 - **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's environment are settings-page work today; a key-callable path for them is being built. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route for them.
 - **The account-wide environment declaration is the exception, and the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it. Use the verb; do not send them to a page for it.
 - **Their tenant, as them.** Everything goes through the CLI and the person's own login. You never name another tenant, and you never ask for a key you could avoid — the keyless login needs nothing pasted.

package/skills/catalyst-onboard/references/declaring-a-repository.md

@@ -8,15 +8,36 @@ The cloud containers build and test the repository. They need the names of the v
 2. For each name, record the file it came from: a `.env.example` (never `.env`, which holds live values), a CI secret in a workflow's `env:` block, or a platform binding. A name you cannot tie to a file is a guess. Say so instead of listing it.
 3. Mark whether the container needs it to build and test, or only to deploy. Containers build and test. They do not deploy.
 4. Leave platform bindings and deploy-only CI secrets out by default. The platform supplies a binding at run time, and no build or test reads a deploy-only secret. Include one only when the person says the build needs it, and say why.
-5. Write the names into `catalyst.env.json` at the repository root and open a pull request. Use that exact name and place; the cloud reads no other file. It reads the file once the pull request merges to the default branch. A tenant owner or admin then approves it at Settings → Repositories → the repository → Environment, and the person enters the values on that page.
+5. Write the names into `.catalyst/catalyst.toml` and open a pull request. Use that exact path. The cloud reads no other file, and an older `catalyst.env.json` is ignored. Once the pull request merges, each push to the default branch that touches the file makes the cloud read it and propose it as a new revision. A tenant owner or admin opens Settings → Repositories → the repository → Environment → Setup declaration and clicks Approve this revision. The person enters the values on the same page's Environment variables and Secrets tabs.
 
 ## The file's shape
 
-`"version": 1` plus eight arrays, each present even when empty: `toolchains`, `systemPackages`, `setup`, `verify`, `services`, `environment`, `agentAssets`, `provenance`. The repository's Environment page in the app shows a complete, valid example. Start from it rather than from memory.
+`[project]` with `linear_team` is required. Every other section is optional. The names a build needs go under `[environment]`:
 
-- `setup` and `verify` carry this repository's own install and test commands. `command` is an argument list, not a shell string.
-- Each name under `environment` says whether it is `required`. Add `"secret": true` beside a secret.
-- Each `provenanceIds` entry points at a record under `provenance` that names the file the name came from.
+```toml
+#:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json
+
+[project]
+linear_team = "ENG"
+
+[[environment.variables]]
+name = "DATABASE_URL"
+required = true
+
+[[environment.variables]]
+name = "STRIPE_API_KEY"
+required = true
+secret = true
+
+[[environment.setup]]
+name = "install"
+run = ["npm", "ci"]
+```
+
+- `linear_team` is the key of the Linear team this repository's work belongs to.
+- Each `[[environment.variables]]` entry names one variable and says whether it is `required`. Add `secret = true` for a secret. Names only: a value never goes in this file.
+- `[[environment.setup]]` steps carry this repository's own install commands. `run` is an argument list, not a shell string, and `name` is kebab-case. `verify` steps have the same shape and carry the test commands. `toolchains`, `system_packages`, `services` and the other `[environment]` tables are optional; the schema lists their fields.
+- The `#:schema` line lets an editor check the file as you type.
 
 ## After the merge
 

package/skills/catalyst-onboard/references/local-sync.md

@@ -0,0 +1,15 @@
+# Optional local events and replica
+
+**For:** a person who wants an on-machine event file and searchable replica. The normal API-backed skills work without this, so ask before starting a background writer.
+
+**You run:** `node scripts/local-sync.mjs` to show the current local state. Only if the person opts in, run `node scripts/local-sync.mjs --start`. The script uses `catalyst-skills replica start --detach`, whose writer also starts the local event cache. It waits up to 90 seconds; `--wait <seconds>` sets a bounded wait from 0 to 300.
+
+**Read back:** `Local sync current` only when both the replica and event cache have live writer heartbeats and each cursor equals its own cloud head. A detached process starting, one fresh heartbeat alone, or replica freshness alone does not prove event freshness. `catalyst-skills replica status --probe --json` checks the replica cursor; `catalyst-skills events status --probe --json` checks the separate event cursor. Either command can report stale or unknown; unknown means the cloud comparison could not be proved, not that the cache is stale. Exit 0 means current, 1 stale, 2 unknown or not connected, and 3 absent. Do not tell the person local data is current unless the combined check says so.
+
+**Owner:** you check and, with the person's opt-in, start. The local writer is optional. A reboot recovery service is separate work; if this machine restarts, recheck status before relying on local data.
+
+## First ticket event
+
+Ask before starting the local writer. Before the person moves a card, run `node scripts/local-sync.mjs --start` after they opt in and wait until it reports current. Then run `catalyst-skills events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Once the card is moved, run `catalyst-skills events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed. Do not guess an event type. The explicit cursor lets `wait-for` find the event if it reached the local cache before the command began.
+
+Exit 0 prints a matching event after the recorded baseline and proves it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` remains the API-backed source for why a ticket can or cannot run.

package/skills/catalyst-onboard/references/skill-sources.md

@@ -18,6 +18,9 @@ Install both packs on a workstation used for coding and tenant operations. Each
 - The global lock is `$XDG_STATE_HOME/skills/.skill-lock.json` when `XDG_STATE_HOME` is set, else `~/.agents/.skill-lock.json`. A project uses its own `skills-lock.json`.
 - The installer writes relative links. Resolve each with `readlink -f` before you compare paths.
 
+
+The `npx skills add --all` command replaces existing same-named directories and links. Before a first install or refresh on an existing machine, read the lock above. Inspect every same-named agent destination. Proceed only when each destination is absent or a verified, unmodified copy of the intended pack or its symlink. A lock entry alone does not verify every destination. Keep independent, changed, or uncertain copies in place and resolve the conflict before adding either pack. Do not schedule raw add commands as an unattended refresh.
+
 ## Is each pack there
 
 `catalyst-skills ready` checks the Cloud pack only. Check `catalyst-onboard/SKILL.md` (Cloud pack) and `research-codebase/SKILL.md` (development pack) in the intended directory. If both are there, have the person type `/catalyst-onboard` (`$catalyst-onboard` in Codex).
@@ -28,8 +31,8 @@ Inventory source and scope before removing anything:
 
 1. Run `claude plugin list` and record whether `catalyst-dev@catalyst` is installed and at which scope.
 2. Inspect the selected agent's home skill directory and the current project's skill directory separately. Read any `skills-lock.json` files and source/provenance markers. A folder name alone does not prove which repository supplied it. Check whether `.claude/skills` is a symlink to another skills directory before changing either path.
-3. If the old plugin is active, remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. Keep `catalyst-dev@catalyst-dev-skills` and `catalyst@catalyst-cloud`. If old skill copies are present, remove only copies whose recorded source is the deprecated local runtime. Keep unrelated skills and plugin installs.
+3. If the old plugin is active, remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. Keep `catalyst-dev@catalyst-dev-skills` and `catalyst@catalyst-cloud`. For a copied skill whose lock source names the deprecated Catalyst runtime repository, use `npx skills remove <name> -g -y` only when every existing global agent path is that canonical copy or a symlink to it. Omit `-g` for a proven project install and inspect every same-named project agent path first. The command removes that name across agent directories. Leave independent or uncertain copies in place and report the conflict.
 4. Install the replacement pack or packs in the intended scope with the commands above. For the Cloud pack, omit `-g` only when a project-scoped install is intended. Do not use a blanket `npx skills remove --all` during migration.
-5. Read back the plugin list or skill lock and the destination skill folders. Start a new agent session after changing Claude plugins.
+5. Read back the plugin list, the lock for each changed scope, and the destination skill folders. Start a new agent session after changing Claude plugins.
 
 Do not delete a Catalyst checkout, local project data, or a same-named skill whose source is not known. If the source or scope is ambiguous, stop and report what is unclear before removing anything.

package/skills/catalyst-onboard/references/the-one-path.md

@@ -1,12 +1,11 @@
 # The one path
 
-Nine steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide.
+Eleven steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide. Connect the tenant's Linear workspace before starting personal Linear consent (3a). Install the tenant's GitHub App and register its repository before starting personal GitHub consent (6a).
 
 Walk them **one at a time**. Before each step say what you are about to do and why; after it, show what actually came back. `node scripts/where-am-i.mjs --next` decides which step you are on — never your memory of the last turn.
 
 Each step below states: what it is for, what you run or hand over, **what you read back to prove it landed**, and **who owns it**.
 
----
 
 ## 0 — Where are we
 
@@ -18,8 +17,6 @@ Each step below states: what it is for, what you run or hand over, **what you re
 
 **Owner:** you.
 
----
-
 ## 1 — Connect this machine
 
 **For:** giving this machine a credential, so every later read is the person's own.
@@ -32,8 +29,6 @@ Each step below states: what it is for, what you run or hand over, **what you re
 
 If it refuses, stop here and use the `connect-me` skill; it owns every failure mode of this step.
 
----
-
 ## 2 — Who you are
 
 **For:** the person grain. A connected machine does not mean an active seat, and an active seat does not mean their Linear identity is matched.
@@ -42,9 +37,7 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Read back:** their label and role, and whether their Linear identity is matched.
 
-**Owner:** an unmatched Linear identity is fixed by a tenant owner or admin in Settings → Members. A seat that is not active is the same. Say which, and move on — neither blocks the steps below, but an unmatched identity means "what needs me" will show everyone's asks until it is fixed, and they should know that now rather than later.
-
----
+**Owner:** a personal Linear connection normally matches the person's Linear identity automatically. If it remains unmatched after personal consent, run `catalyst-skills identity linear status`, then `catalyst-skills identity linear options`. Let the member select their own listed identity and run `catalyst-skills identity linear set <linearUserId>`. The command reads the result back. An automatically resolved identity cannot be replaced; an existing claim conflict needs a tenant owner or admin. An inactive seat also needs an owner or admin. Say which finding the instrument reported.
 
 ## 3 — Connect Linear
 
@@ -56,7 +49,15 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin, in a browser. **This is a browser step by construction** — it is an authorization grant, and no key can perform one.
 
----
+## 3a — Connect your personal Linear account
+
+**For:** giving this person's agent its own provider access. The tenant's Linear connection and GitHub App serve the tenant; they do not prove that this member has approved personal grants.
+
+**You run:** `catalyst-skills connections personal linear start`. It gives a short-lived URL and tries to open it. The person approves in their own browser. If the browser does not open, give them the URL printed by the command. Never paste a provider token into a prompt.
+
+**Read back:** after approval, run `catalyst-skills connections personal linear status`. `node scripts/where-am-i.mjs` also reads the personal grant statuses. A URL opening is not proof that a grant landed.
+
+**Owner:** you start and check; the member approves in a browser. A usable personal Linear grant normally binds its viewer automatically. If identity remains unmatched, use `catalyst-skills identity linear options` for supported self-service recovery. Never choose a roster entry on the member's behalf. An already-resolved or already-claimed refusal needs an owner or admin to inspect the conflict.
 
 ## 4 — Pick one project, and map its stages
 
@@ -70,7 +71,6 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 ⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: pick the project they care least about breaking.
 
----
 
 ## 5 — Install the GitHub App
 
@@ -82,7 +82,6 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin, in a browser. **Browser by construction**, same reason as step 3.
 
----
 
 ## 6 — Register the repository
 
@@ -94,13 +93,16 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin. ⛔ **Registering is settings-page work today**; a key-callable path is being built. ⛔ A repository registered without a project attached is the trap here: the call succeeds, the repository is listed, and nothing can ever dispatch into it. Make sure they attach the project in the same form, and say why.
 
----
+
+## 6a — Connect your personal GitHub account
+
+**For:** letting Catalyst act as you in GitHub. This grant is separate from the tenant's GitHub App installation. **You run:** `catalyst-skills connections personal github start`, only after the GitHub App is installed and the repository is registered. The browser flow is the same as 3a. **Read back:** `catalyst-skills connections personal github status`; a connected result confirms the personal grant. **Owner:** you start and check; the member approves in a browser.
 
 ## 7 — Declare what the containers need
 
 **For:** the environment a phase runs in — the names of the variables and secrets the person's code needs. Names leave the machine; values are entered once, by them, in the app.
 
-⭐ **This is the one setup step you can actually do.** Every other step above is a page. This one is a command, and it is worth saying so to the person.
+You can read, propose, and approve the account-wide declaration through the CLI if this member has an admin or owner seat. Personal connection initiation and status are also CLI actions; the provider approval remains in the browser.
 
 **You run:** `catalyst-skills environment` first, to read what the tenant already declares — the current revision, whether it is approved, and which revision a phase's checkout actually carries. Those last two are different things more often than people expect: a proposal that nobody approved changes nothing.
 
@@ -116,11 +118,10 @@ Add `--approve` to approve exactly the revision that propose just returned, whic
 
 **Owner:** you can read it from any active seat; proposing and approving need an admin or owner seat, and the cloud refuses with that sentence if the person does not have one — read the refusal to them rather than retrying.
 
-⛔ **Values never pass through you.** The declaration carries the *names* a build needs. The values are entered by the person, once, in the app, and nothing you run ever sees them. Say that plainly; a person asked for a secret by an agent is right to be suspicious. The names one repository needs go in its own committed `catalyst.env.json`. See `references/declaring-a-repository.md`.
+⛔ **Values never pass through you.** The declaration carries the *names* a build needs. The values are entered by the person, once, in the app, and nothing you run ever sees them. Say that plainly; a person asked for a secret by an agent is right to be suspicious. The names one repository needs go in its own committed `.catalyst/catalyst.toml`. See `references/declaring-a-repository.md`.
 
 If they do not know what their build needs yet, skip this step. It blocks nothing until a phase needs a secret.
 
----
 
 ## 8 — A coding account, and a host
 
@@ -136,13 +137,12 @@ If they do not know what their build needs yet, skip this step. It blocks nothin
 
 **You run:** `catalyst-skills ready`. Its READY does not cover step 8; the script does. Read them the verdict and every failing line, each with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything — a project check failing is not something re-running anything on this machine can fix.
 
-**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run.
+**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
 
 **Read back:** what `explain` actually said. If it says the ticket cannot start, the reason it names is the answer — read it to them and use the `how-catalyst-works` skill for what the reason means, then `unstick` if something is holding it.
 
 **Owner:** the card move is theirs. The verdict is the tenant's.
 
----
 
 ## When you are done
 

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -11,6 +11,8 @@ These will never be a command, on any release. Each is an authorization a person
 | approving the login | the URL and short code that `catalyst-skills login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
 | connecting Linear | `<their cloud>/settings/connections` | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
 | installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked." |
+| connecting personal Linear | the URL printed by `catalyst-skills connections personal linear start` | "Approve your own Linear account in this browser. I will check the grant status afterward." |
+| connecting personal GitHub, after the tenant GitHub App is installed and its repository is registered | the URL printed by `catalyst-skills connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
 
 Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
 
@@ -24,7 +26,7 @@ These are settings pages today because the routes behind them take a browser ses
 | checking a project's readiness, or re-checking it | the same page | "I can read the verdict your tenant last stored, from the contract. Asking for a fresh check is on that page." |
 | mapping stages, or adopting the workflow | the same page, per project | "Pick one project, then **Map my stages** — or **Adopt the Catalyst workflow** if you want Catalyst's stages created for you." |
 | registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
-| approving the environment **for one repository**, and entering its values | that repository's environment section under `<their cloud>/settings/repositories` | "The names come from `catalyst.env.json` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst-skills environment` does those.) |
+| approving the environment **for one repository**, and entering its values | that repository's Environment page under `<their cloud>/settings/repositories`: the Setup declaration tab's Approve this revision button approves, and the Environment variables and Secrets tabs take the values | "The names come from `.catalyst/catalyst.toml` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst-skills environment` does those.) |
 
 ⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
 

package/skills/catalyst-onboard/references/who-fixes-what.md

@@ -7,7 +7,7 @@ Setup is seven parts. Each has one instrument, and each instrument answers about
 | part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
 | -- | -- | -- | -- | -- |
 | **machine** | `catalyst-skills status`, and the non-team checks of `catalyst-skills ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
-| **person** | `catalyst-skills me` | the credential resolves to this person, with a role, and whether their Linear identity is matched | that their seat is active, or that they may change tenant settings | a tenant owner or admin, Settings → Members |
+| **person** | `catalyst-skills me`, and `catalyst-skills connections personal <linear|github> status` | the credential resolves to this person, shows their role and Linear identity match, and reports each personal grant's state | that their seat is active, or that they may change tenant settings | the member approves missing or expired personal grants in a browser; an owner or admin handles seat or identity conflicts in Settings → Members |
 | **account** | `catalyst-skills contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
 | **project** | `catalyst-skills contract --path teams`, and the `team:` checks of `ready` | for each project **that has been mapped**: its readiness verdict and each failing check by name | that this is every project they have — see below | a tenant owner or admin, `<their cloud>/settings/linear-teams` |
 | **repository** | `catalyst-skills contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
@@ -34,7 +34,7 @@ Setup is seven parts. Each has one instrument, and each instrument answers about
 
 - **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst-skills install`; a stale contract is `catalyst-skills contract --refresh`; a missing CLI path is one more `catalyst-skills login`.
 - **A project check failed.** ⛔ **Nothing you run on this machine can move it.** Name the check, name the project, and name the owner — the `who` field carries the tenant's own owners and admins. Point at `<their cloud>/settings/linear-teams`. Then stop. Re-running `ready` in a loop is the failure this section exists to prevent: it will keep saying NOT READY for a reason that lives somewhere else entirely.
-- **A check is a note.** Notes never move the verdict. A stale or absent replica is optional; a check that has never been run is waiting, not failing; a check the engine could not run is unknown, which is not a pass and not a failure. Say which of the three it is.
+- **A check is a note.** Notes never move the verdict. A stale or absent replica or event cache is optional; an unknown freshness probe means the cloud comparison could not be proved. The API-backed skills still work. Say whether the local cache is absent, stale or unknown, and ask before starting the optional writer.
 
 ## When to stop rather than continue