ctxr-cli 0.36.0 → 0.38.0

package/templates/skills/ctxr-second-opinion.md

@@ -1,9 +1,9 @@
 Get an independent read from models built by different labs before you commit to something you cannot
 cheaply take back, or when your own taste is one vote among several. A second opinion from the same model
 family you are running as mostly repeats you, so this skill sends the work to three command-line tools backed
-by three different families and hands you their answers. `ctxr second-opinion` does the mechanics: it launches
-the tools, contains them, times them out, and anonymizes what comes back. It does not decide anything and it
-never carries out what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
+by three different families and hands you their answers. `ctxr second-opinion critique` and its `poll`
+sibling do the mechanics: they launch the tools, contain them, time them out, and anonymize what comes
+back. They do not decide anything, and they never carry out what they review. Weighing the answers is your job, and steps 4 and 5 are how.
 
 ## 1. Critique, poll, or just answer?
 
@@ -41,18 +41,27 @@ The preflight pings each tool with that tier's model and names the model it test
 longer offers fails only at the tier that uses it.
 
 If one is down, stop and give the operator the two real choices: sign that tool in and re-run, or continue
-with the others by rerunning `ctxr second-opinion` with `--only` and naming them. Do not quietly run with one
+with the others by rerunning `ctxr second-opinion critique` with `--only` and naming them. Do not quietly run with one
 model. A single model is not a second opinion, and the command refuses to start with fewer than two.
 
 Failure signatures: `Not logged in` means Claude needs `/login`; a `401` or an invalid refresh token from
 Codex means `codex login`; an agy call that hangs usually means its sign-in expired and it needs one
 interactive run.
 
+Through the store's server, the operator signs the tools in on the server. Tell the person which tool is
+down. Ask them to pass that on to the operator.
+
+Each tool runs in a new folder that is its home and holds only its own login. Where the machine supports it,
+the kernel also stops the tool from reading anything outside that folder, and the preflight reports
+`confined: yes`. Why: a plan can carry instructions from whoever wrote it, and a tool that cannot read a
+secret cannot quote it. The store's server runs a second opinion only when it is confined.
+
 The tools see only an allowlisted environment: the search path, home, locale, proxies, and their own login
 variables. Forge and contexture variables never reach them. When a tool fails because it needed a variable the
 allowlist dropped, a failing `ctxr second-opinion preflight` names the variables it withheld (names, never
 values). Name that variable in `CTXR_SECOND_OPINION_PASS_ENV` for the run. A forge or contexture variable there
-stops the command before any tool starts.
+stops the command before any tool starts. Through the store's server, these variables are the operator's to
+set on the server. Ask the operator to set one. Do not try to set it from the conversation.
 
 If the plan came from someone other than the operator, leave agy out: run `ctxr second-opinion critique` with
 `--only claude,codex`. Claude runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that
@@ -61,7 +70,8 @@ an accident and not an attack.
 
 ## 3. Run a critique
 
-Write the plan to a file. The reviewers can only cite what is written down, and they cite by step number:
+Write the plan down in this shape. Why: the reviewers can only cite what is written down, and they cite by
+step number.
 
 ```
 # Plan: <one-line goal>
@@ -81,19 +91,24 @@ S2. <step>
 - Irreversible: <steps>
 ```
 
-Then run it:
+In a shell, write the plan to a file and run:
 
 ```
 ctxr second-opinion critique --plan-file <plan> --out <dir>
 ```
 
+Through the store's server, give the plan as `input`. Run the `ctxr` tool with `args` set to
+`["second-opinion", "critique", "--plan-file", "@input"]`. The critiques come back in the result.
+
 Three reviewers each read the plan alone: structure and ordering, failure modes and trust boundaries,
 simplicity and cost. None sees another's answer. That is deliberate: reviewers who read each other converge
 on whoever spoke first, and a correct one gets talked out of it. Do not add a second round.
 
 The command prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
 never prints which model wrote which letter. With `ctxr second-opinion critique --json` the same result, with
-the manifest, arrives as one envelope instead. A **blind** critique returned a well-formed verdict but cited
+the manifest, arrives as one envelope instead. With `ctxr second-opinion critique --print`, the command prints
+each critique under its letter, then the letter table, and writes no files. Through the store's server it
+always prints. A **blind** critique returned a well-formed verdict but cited
 nothing in the plan, so it was written without reading it; it does not count. **Partial** means fewer than
 two valid critiques, and the command then exits with the failed-check status rather than success: say so at
 the top of your answer and do not call anything a consensus.
@@ -112,14 +127,17 @@ default level. Measured on a short plan at the default tier, a critique took one
 quicker and costs less. A deeper pass is a choice: with `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max`, Claude on
 Opus alone took over eight minutes on a short plan. That is close to the command's ten-minute limit per tool,
 and Fable is slower than Opus; raise it with `ctxr second-opinion critique --timeout <seconds>` for such a
-run. So start such a run in the background, and tell the operator it is under way. A machine that pins its own
+run. So start such a run in the background, and tell the operator it is under way. Through the store's
+server, each tool gets at most 200 seconds and the whole run four minutes. Run a deep pass in a shell.
+Why: the chat app stops waiting for a tool after about four minutes. A machine that pins its own
 Codex effort in its configuration is overridden by the catalog default; set `CTXR_SECOND_OPINION_CODEX_EFFORT`
 to use another.
 
 ## 4. Synthesize on the letters first
 
 Read the `critique-A`, `critique-B` and `critique-C` files and write your synthesis before you open
-`manifest.json`. You share a model family with one of the reviewers, and models rate their own family's
+`manifest.json`. When the critiques were printed, write your synthesis before you read the letter table
+below them. You share a model family with one of the reviewers, and models rate their own family's
 writing higher. Reading letters first is what keeps that from steering you. Then open the manifest and
 attach roles and models to the letters in the final report.
 
@@ -166,12 +184,15 @@ for a typo.
 
 ## 6. Run a poll
 
-Write the question and the options to a file, then:
+Write the question and the options down. In a shell, write them to a file and run:
 
 ```
 ctxr second-opinion poll --prompt-file <question>
 ```
 
+Through the store's server, give them as `input`. Run the `ctxr` tool with `args` set to
+`["second-opinion", "poll", "--prompt-file", "@input"]`. The answers come back in the result.
+
 The same question goes to all three models, each answering with a pick, reasons, and anything surprising.
 This mode names its files by model, because what you are reading is whether the models agree.
 
@@ -203,6 +224,6 @@ include your own family, say so.
   yourself.
 - Model names change faster than releases. When a default is stale, set
   `CTXR_SECOND_OPINION_CLAUDE_MODEL`, `CTXR_SECOND_OPINION_CLAUDE_EFFORT`, `CTXR_SECOND_OPINION_CODEX_MODEL`,
-  `CTXR_SECOND_OPINION_CODEX_EFFORT` or `CTXR_SECOND_OPINION_AGY_MODEL` in the environment for the run. Nothing about the lineup lives in the store's configuration.
+  `CTXR_SECOND_OPINION_CODEX_EFFORT` or `CTXR_SECOND_OPINION_AGY_MODEL` in the environment for the run. Nothing about the lineup lives in the store's configuration. Through the store's server, the operator sets them on the server.
 - The scratch files under the output directory hold each reviewer's raw output and are safe to delete when the
-  operator has the synthesis. They can contain the plan, so do not commit them.
+  operator has the synthesis. They can contain the plan, so do not commit them. A printed run writes none.

package/templates/skills/ctxr-session-lifecycle.md

@@ -22,10 +22,11 @@ session's worktree is gone. The name becomes a git ref and a directory, so keep
 that should not be written down.
 
 Before starting, bring the store's canonical clone up to date — the repository's main worktree, not
-whichever checkout you are standing in. From the canonical clone: `git fetch origin`, then
-`git merge --ff-only origin/__DEFAULT_BRANCH__`. If it is on another branch, carries uncommitted
-changes, or the fast-forward fails because it has diverged from origin, report exactly that and start
-the session anyway — never check it out, reset it, stash, or force the merge to make it comply. The
+whichever checkout you are standing in. In a shell, run `ctxr sync`; through the store's server, skip
+this step, because the server keeps its own clone current. It fetches `__DEFAULT_BRANCH__` and
+fast-forwards the canonical clone, and leaves it alone when it is on another branch, carries uncommitted
+changes, or has diverged from origin. If it reports that, report exactly that and start the session
+anyway — never check it out, reset it, stash, or force the merge to make it comply. The
 session's base is unaffected either way, because `ctxr session start` branches from the
 `origin/__DEFAULT_BRANCH__` it fetches itself. What a stale clone costs is the context you read out of
 it: notes, catalog sections, the graph document, and AGENTS.md would all be the versions it last had.
@@ -56,7 +57,7 @@ It reports each session with its open pull request and the decision made on the
 
 Skip this section when the store mounts no other stores under `shared/`.
 
-- After you bring the canonical clone up to date, run `ctxr shared-stores sync`. It clones a missing mount and fast-forwards the others.
+- After you bring the canonical clone up to date, run `ctxr shared-stores sync` in a shell; through the store's server, skip this step, because the server keeps no mounts. It clones a missing mount and fast-forwards the others.
 - Report a mount that sync left alone, with its reason. Do not reset, stash or force it. Why: local work in a mount is somebody's session.
 - To write into a mount for the work of this store's session, change into `shared/<name>`. Run `ctxr session start --joins <session>` there, with this store's session name. Why: the mount's session then joins this one, and one decision covers both pull requests.
 - The command refuses outside a mount, or for a session this store does not have. Report the refusal. Do not start a plain session instead.

package/templates/skills/mcp/_layer-step.md

@@ -0,0 +1,18 @@
+## 1. Which layer?
+
+The connector's instructions list this store's layers, each with its description, under *This store*;
+AGENTS.md's "Placing a new note" section lists them too. Choose by what the content fundamentally IS, not by
+surface keywords; a label on a location says nothing about what is actually kept there.
+
+- A layer whose description names an end state, a finish line or a deadline takes only what has a finish
+  line: if it never closes, it does not belong there. An item in that layer that can never close is a smell
+  — it either clutters the layer as open-forever or gets retired prematurely. Never create one on purpose;
+  an ongoing responsibility with a standard to maintain belongs in a layer whose description says so.
+- A layer whose description says it holds completed, abandoned or inactive items is where the other layers'
+  finished or dropped items go — never a first placement. Retire a note with `ctxr archive <path>` (a
+  tracked move; frontmatter untouched).
+
+If the store lists no layers, there is no layer decision: place the note next to the notes it will link to
+most (`ctxr graph query neighbors <path>` on the closest existing note shows that cluster) and let wikilinks
+carry the structure. If no layer fits, use the catch-all location AGENTS.md names and revisit the placement
+later.

package/templates/skills/mcp/_relation-grouping-step.md

@@ -0,0 +1,5 @@
+5. Group proposals by the relation vocabulary the connector's instructions list under *This store*, each
+   with its definition. The section headings carrying these names are what `ctxr graph build` types edges
+   from, so a link written under the right heading becomes a typed edge on the next build. Format each item
+   as `[[Note]]` — reason. Choose between two adjacent relations by their definitions, not their names, and
+   remember that an edge is recorded only on the note carrying the link.

package/templates/plugin/claude-mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "__NAME__": {
-      "type": "http",
-      "url": "__MCP_URL__"
-    }
-  }
-}

package/templates/skills/mcp/_preamble.md

@@ -1,44 +0,0 @@
-## Before this skill: the store's tools stand in for a checkout
-
-You are working through this store's server, not in a checkout of it. Nothing runs a shell here, so no
-`git`, `gh` or `ctxr` command runs as written. The skill below was written for an agent with a checkout:
-follow it as written, and take each step it names through the tool these tables give.
-
-### Commands
-
-__COMMAND_TABLE__
-
-A command marked none has no counterpart here: skip that step and say nothing about it. Each other tool takes its command's options as fields, each named for its option without the leading
-dashes, and the session the command names as `session`: the session worktree's directory name, which
-`session_start` returns and `session_list` lists. `session_start` takes the session's name as `label`.
-
-Every other `ctxr` step runs through the `ctxr` tool when the command only reads, and through `ctxr_write`
-when it writes. Pass the words after `ctxr` as `args`, one word per entry: a step that says to run
-`ctxr lint` is the `ctxr` tool with `args` set to `["lint"]`. Name a session as `session` to run the command
-in that session's working tree; `ctxr_write` always needs one. When a command reads a file you prepared,
-pass the file's text as `input` and write `@input` in `args` where its path goes.
-
-### Git steps
-
-__GIT_STEP_TABLE__
-
-Commits, pushes and pull requests happen only in `session_submit`. A step marked none is the server's own
-work: it keeps the store's clone current, and `session_start` branches from the freshly fetched default
-branch. Skip that step and say nothing about it.
-
-### Paths
-
-`session_start` returns the session's root, a path such as `__WORKTREES_PATH__<directory>/`. Every path the
-skill names is relative to the store; inside a session it goes under that root, so the note `work/a.md` in
-that session is `__WORKTREES_PATH__<directory>/work/a.md` for `Read`, `Edit`, `Write`, `Move`, `Delete`,
-`Grep` and `Glob`. A path without a session root reads the store as it was last approved, and a write to one
-is refused. A change rests uncommitted in its session until `session_submit`.
-
-### Sessions across conversations
-
-The server keeps a session between conversations, but it cannot tell two conversations apart. At the
-start of a conversation, call `session_list` and mention each open session: what it holds uncommitted,
-and any requested changes on its pull request. Work in the session the person names, or start one.
-
-Where the skill hands off to a skill this environment does not carry, such as landing or upgrading, or
-asks you to work inside a store mounted under `shared/`, that step is not yours here: a person lands an approved change from the store's approval page.