triss-coworker 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-05-08
+
+### Added
+
+- New `triss agent-help` command prints the full delegation cookbook
+  (CLI examples, model presets, dynamically-rendered integration
+  sections) on demand. The nano `CLAUDE.md` / `AGENTS.md` block points
+  here so the long reference is loaded only when an agent actually
+  needs it.
+- Shared `src/agent-rules.js` module owns template rendering for both
+  `triss init` (nano variant) and `triss agent-help` (full variant).
+  The `{{INTEGRATIONS}}` placeholder and the MCP-hint blockquote now
+  apply only to the full variant.
+- New full-cookbook templates: `templates/claude-full.md` and
+  `templates/codex-full.md` (the long form previously in
+  `templates/claude.md` / `codex.md`).
+
+### Changed
+
+- **`triss init` now writes a ~17-line nano block** instead of the
+  ~150-220 line full cookbook. The block names the Triss MCP tools,
+  states when to delegate vs not, and points at `triss agent-help`.
+  Net effect: ~6-8× fewer always-loaded tokens per session for every
+  project that has run `triss init`. Existing users: re-run
+  `triss init` (with the same `--target` / `--global` flags as
+  before) to shrink the block in place — the marker-based
+  `replaceBlock` swap preserves all surrounding content.
+- The Codex nano block points at `triss agent-help --target codex`
+  so Codex agents receive AGENTS.md-flavored output instead of the
+  Claude-flavored default.
+
+### Fixed
+
+- `agent-rules.js` now calls `loadEnvFiles()` before checking
+  `envReadiness()`. Previously `triss agent-help` only saw integrations
+  whose credentials were exported into `process.env` — credentials
+  stored in `~/.config/triss/.env` (the wizard's default destination)
+  or `./.triss.env` were silently ignored, so agents never saw their
+  Jira/Linear/GitHub sections in the cookbook. `loadEnvFiles` is now
+  exported from `src/config.js` for direct reuse.
+- `test/e2e-integration.test.js`'s "config set TRISS_WORKER_API_KEY
+  then getConfig returns it" test now `chdir`s to a fresh tmp project
+  dir, matching its sibling tests in the same file. Previously it ran
+  from the repo cwd, so a contributor's local `.triss.env` would
+  shadow the value the test wrote to the global file. CI happened to
+  pass because the gitignored file was absent there; on developer
+  machines it could fail spuriously.
+
+### Internal
+
+- Added `.mcp.json` to `.gitignore`. The file is produced by
+  `triss mcp install --local` and bakes the developer's absolute
+  project path into a JSON `env.TRISS_PROJECT_ROOT` field — must not
+  be committed.
+- New regression tests in `test/agent-help.test.js`:
+  full-cookbook rendering, target switching, integration injection,
+  MCP-hint detection, and the env-file readiness path (the last one
+  spawns the CLI in a subprocess so module-level `homedir()`
+  constants in `src/secrets.js` resolve relative to the temp HOME).
+
 ## [0.15.2] — 2026-05-08
 
 ### Changed

package/README.md

@@ -185,6 +185,13 @@ Agent reads the rules and invokes Triss via the shell. No special
 setup. Best when you also want the same commands available outside the
 agent (in your own scripts, CI, etc).
 
+The block is intentionally tiny (~15 lines): it names the MCP tools,
+states when to delegate vs not, and points at `triss agent-help` for the
+full cookbook. The cookbook is rendered on demand — the agent reads it
+once when it actually needs the long reference, instead of loading 200
+lines of instructions into every session. This keeps the always-on
+context cost negligible compared to the savings Triss provides.
+
 ### Option 2 — MCP server (deeper integration)
 
 ```bash
@@ -230,7 +237,10 @@ Full reference: [docs/mcp.md](docs/mcp.md).
 
 The root `CLAUDE.md` and `AGENTS.md` in this repository are contributor
 instructions for working on Triss itself. The files under `templates/` are
-what `triss init` renders into other projects.
+what `triss init` and `triss agent-help` render into other projects:
+`claude.md` / `codex.md` are the nano variants written by `init`, and
+`claude-full.md` / `codex-full.md` are the long cookbook served by
+`agent-help`.
 
 ## What it does
 
@@ -247,7 +257,8 @@ and writing**.
 | `triss review`     | Code review on current branch or a PR (diff + linked ticket) | The agent reading the whole diff |
 | `triss commit-msg` | Generates a commit message from staged diff           | Hand-writing or copy-pasting from web LLMs |
 | `triss usage`      | Cumulative cost / token usage with per-project breakdown | Squinting at stderr after each call |
-| `triss init`       | Drops a delegation block into `CLAUDE.md` / `AGENTS.md` | Hand-writing routing rules         |
+| `triss init`       | Drops a tiny (~15 line) delegation block into `CLAUDE.md` / `AGENTS.md` | Hand-writing routing rules         |
+| `triss agent-help` | Prints the full delegation cookbook on demand (the nano block points here) | A 200-line CLAUDE.md that always loads |
 | `triss status`     | Shows current model + key + .env sources              | —                                   |
 | `triss config`     | Interactive credential management                     | Manual `.env` editing               |
 | `triss mcp`        | Register Triss as MCP server in Claude Code           | Editing `~/.claude.json` by hand    |
@@ -420,11 +431,14 @@ Two design rules:
 `triss status` shows each integration's env-var readiness so you know what
 still needs configuring.
 
-`triss init` injects per-integration delegation rules into your
-`CLAUDE.md` / `AGENTS.md` **only for integrations whose credentials are
-present**. Add a Linear key later? Run `triss config wizard linear` then
-`triss init` again — the new section appears automatically. Users who
-never use Jira never see Jira instructions in their agent's prompt.
+`triss agent-help` inlines per-integration delegation rules into the full
+cookbook **only for integrations whose credentials are present**. Add a
+Linear key later? Run `triss config wizard linear`, then the next time the
+agent runs `triss agent-help` the Linear section appears automatically.
+Users who never use Jira never see Jira instructions in the cookbook.
+
+(The nano `triss init` block stays the same regardless — integration
+hints live in the on-demand cookbook, not in the always-loaded block.)
 
 ### Adding your own integration
 
@@ -439,7 +453,7 @@ integration in ~80 lines is documented end-to-end in
    `IntegrationError`).
 4. Drop tests in `test/<name>-*.test.js` (mock `globalThis.fetch`).
 5. Run `triss --help` — your subcommand appears automatically. The
-   wizard, `triss status`, and `triss init` (CLAUDE.md / AGENTS.md generation) all
+   wizard, `triss status`, and `triss agent-help` (full cookbook) all
    pick up the new manifest with no further wiring.
 
 ## Models

package/bin/triss.js

@@ -26,6 +26,7 @@ import {
 } from '../src/commands/mcp.js';
 import { runCommitMsg } from '../src/commands/commit-msg.js';
 import { runInit } from '../src/commands/init.js';
+import { runAgentHelp } from '../src/commands/agent-help.js';
 import { runStatus } from '../src/commands/status.js';
 import { runCompletion } from '../src/commands/completion.js';
 import {
@@ -146,6 +147,12 @@ program
   .option('--reset', 'clear the usage log (cannot be undone)')
   .action(wrap(runUsage));
 
+program
+  .command('agent-help')
+  .description('Print the full Triss delegation cookbook (the nano block in CLAUDE.md / AGENTS.md points here)')
+  .option('-t, --target <agent>', 'agent flavour for headings (claude | codex)', 'claude')
+  .action(wrap(runAgentHelp));
+
 program
   .command('status')
   .description('Show current configuration: API key, models, .env sources')

package/docs/extending.md

@@ -43,13 +43,14 @@ export default {
   ],
 
   // Optional: markdown the agent should see when this integration is
-  // configured. Triss splices these snippets into CLAUDE.md / AGENTS.md
-  // at `triss init` time, but ONLY if all required envVars are present —
-  // so users who don't use your provider never see it in their agent's
-  // instructions. Snippets are also re-rendered on every `triss init`,
-  // so when the user later enables your integration via
-  // `triss config wizard yourthing`, they just re-run `triss init` to
-  // pick up the new section.
+  // configured. Triss splices these snippets into the FULL cookbook
+  // served by `triss agent-help`, but ONLY if all required envVars are
+  // present — so users who don't use your provider never see it in
+  // their agent's instructions. The nano block written by `triss init`
+  // stays unchanged; integration hints live only in the on-demand
+  // cookbook. When the user later enables your integration via
+  // `triss config wizard yourthing`, the next `triss agent-help` call
+  // picks up the new section automatically.
   agentInstructions: {
     claude: '### `triss yourthing` …\n```bash\ntriss yourthing search "..."\n```\n',
     codex:  '### `triss yourthing` …\n…',
@@ -77,8 +78,11 @@ prints them as a red `✗` line — your action handlers should just throw.
 
 ### Wiring into the agent's instructions
 
-The default templates (`templates/claude.md`, `templates/codex.md`) contain
-a `{{INTEGRATIONS}}` placeholder. At `triss init` time Triss:
+`triss init` writes a tiny nano block (~15 lines, no integration content)
+into `CLAUDE.md` / `AGENTS.md`. The full cookbook lives in
+`templates/claude-full.md` / `templates/codex-full.md`, which contain the
+`{{INTEGRATIONS}}` placeholder and are rendered on demand by
+`triss agent-help`. At render time Triss:
 
 1. Loads every integration manifest.
 2. Filters to the ones whose required `envVars` are all set.
@@ -86,9 +90,10 @@ a `{{INTEGRATIONS}}` placeholder. At `triss init` time Triss:
    substitutes the result into the placeholder.
 
 Result: agents get a focused, project-specific delegation guide — no
-mentions of providers the user hasn't configured. If a user later runs
-`triss config wizard yourthing` and adds their token, a follow-up
-`triss init` automatically adds your section to their CLAUDE.md.
+mentions of providers the user hasn't configured — but only when they
+actually need it, so the always-loaded `CLAUDE.md` block stays small.
+If a user later runs `triss config wizard yourthing` and adds their
+token, the next `triss agent-help` call picks up the new section.
 
 ## What `_contract.js` gives you
 
@@ -191,7 +196,7 @@ triss github comment owner/repo 42 --body "..."
 
 Save the file, run `triss --help`, and `github` shows up. After
 `triss config wizard github` (which prompts for `GITHUB_TOKEN`), the next
-`triss init` adds your section to the user's CLAUDE.md or AGENTS.md
+`triss agent-help` adds your section to the on-demand cookbook
 automatically, depending on the selected target.
 
 ## Conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triss-coworker",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Give your AI coding agent a cheap DeepSeek coworker. Delegate bulk reads, boilerplate, and doc updates to save 60-70% of your token budget.",
   "type": "module",
   "bin": {

package/src/agent-rules.js

@@ -0,0 +1,97 @@
+// Shared agent-rules rendering. Used by `triss init` (writes the nano block
+// into CLAUDE.md / AGENTS.md) and by `triss agent-help` (prints the full
+// cookbook on demand). The split keeps the always-loaded block tiny while
+// still letting agents pull the long reference once they need it.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadEnvFiles } from './config.js';
+import { loadIntegrations, envReadiness } from './integrations/_registry.js';
+import { showStatus as mcpStatus } from './mcp/install.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(HERE, '..', 'templates');
+
+export const START_MARKER = '<!-- triss:start -->';
+export const END_MARKER = '<!-- triss:end -->';
+
+export const TARGETS = {
+  claude: {
+    template: 'claude.md',
+    fullTemplate: 'claude-full.md',
+    filename: 'CLAUDE.md',
+    globalDir: '.claude',
+  },
+  codex: {
+    template: 'codex.md',
+    fullTemplate: 'codex-full.md',
+    filename: 'AGENTS.md',
+    globalDir: '.codex',
+  },
+};
+
+export const SUPPORTED_TARGETS = Object.keys(TARGETS);
+
+export async function renderRules(target, { variant = 'nano' } = {}) {
+  const meta = TARGETS[target];
+  if (!meta) throw new Error(`Unknown target: ${target}`);
+  const file = variant === 'full' ? meta.fullTemplate : meta.template;
+  const path = join(TEMPLATE_DIR, file);
+  if (!existsSync(path)) {
+    throw new Error(`Template not found for target "${target}" (${variant}) at ${path}`);
+  }
+  const raw = readFileSync(path, 'utf8');
+  return renderTemplate(raw, target);
+}
+
+// Render the {{INTEGRATIONS}} placeholder. Two layers:
+//   1. If the MCP server is registered, prepend a hint that the same
+//      operations are also available as native MCP tools so the agent
+//      prefers those over the CLI block.
+//   2. Splice in agentInstructions snippets from each integration whose
+//      required env vars are all set (so users who don't use Linear never
+//      see Linear instructions).
+//
+// The nano templates intentionally do NOT include {{INTEGRATIONS}} —
+// rendering on them is a no-op and returns the raw text.
+async function renderTemplate(raw, target) {
+  if (!raw.includes('{{INTEGRATIONS}}')) return raw;
+  // envReadiness() only inspects process.env. Load Triss env files first so
+  // integrations whose credentials live in ~/.config/triss/.env or
+  // ./.triss.env (i.e. the wizard-installed default) are detected as ready.
+  loadEnvFiles();
+  const integrations = await loadIntegrations();
+  const active = integrations.filter(
+    (m) => envReadiness(m).ready && m.agentInstructions?.[target],
+  );
+
+  let mcpHint = '';
+  try {
+    const { present } = mcpStatus('global', { target });
+    if (present) {
+      const sessionLabel = target === 'codex' ? 'Codex' : 'Claude Code';
+      mcpHint =
+        `\n> 💡 **Triss is also available as MCP tools in this ${sessionLabel} session.**\n` +
+        '> Native tools — `triss_ask`, `triss_chat`, `triss_review`, `triss_jira_*`,\n' +
+        '> `triss_linear_*` etc. — are usually faster and have per-tool permissions.\n' +
+        '> Prefer them over the Bash invocations described below; the CLI block stays\n' +
+        '> as a fallback if MCP is not loaded.\n\n';
+    }
+  } catch {
+    /* config unreadable — silently fall back to CLI-only block */
+  }
+
+  let block;
+  if (!active.length && !mcpHint) {
+    block = '';
+  } else {
+    const integrationsBody = active.length
+      ? '\n## Integrations enabled for this project\n\n' +
+        active.map((m) => m.agentInstructions[target].trim()).join('\n\n') +
+        '\n\n'
+      : '';
+    block = mcpHint + integrationsBody;
+  }
+  return raw.replace(/\{\{INTEGRATIONS\}\}\n?/g, block);
+}

package/src/commands/agent-help.js

@@ -0,0 +1,18 @@
+// Print the full Triss delegation cookbook to stdout. The nano block in
+// CLAUDE.md / AGENTS.md points here so the agent loads the long reference
+// only when it actually needs to look something up — saving the per-session
+// token cost of always-loaded full instructions.
+
+import { renderRules, SUPPORTED_TARGETS } from '../agent-rules.js';
+
+export async function runAgentHelp(opts = {}) {
+  const target = (opts.target || 'claude').toLowerCase();
+  if (!SUPPORTED_TARGETS.includes(target)) {
+    throw new Error(
+      `Unknown --target "${target}". Supported: ${SUPPORTED_TARGETS.join(', ')}`,
+    );
+  }
+  const rendered = await renderRules(target, { variant: 'full' });
+  process.stdout.write(rendered);
+  if (!rendered.endsWith('\n')) process.stdout.write('\n');
+}

package/src/commands/init.js

@@ -1,26 +1,20 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import pc from 'picocolors';
 import { getConfig } from '../config.js';
 import { loadIntegrations, envReadiness } from '../integrations/_registry.js';
 import { runWizard } from './config.js';
-import { showStatus as mcpStatus } from '../mcp/install.js';
 import { promptChoice } from '../secrets.js';
+import {
+  TARGETS,
+  SUPPORTED_TARGETS,
+  START_MARKER,
+  END_MARKER,
+  renderRules,
+} from '../agent-rules.js';
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE_DIR = resolve(HERE, '..', '..', 'templates');
-
-const START_MARKER = '<!-- triss:start -->';
-const END_MARKER = '<!-- triss:end -->';
-
-const TARGETS = {
-  claude: { template: 'claude.md', filename: 'CLAUDE.md', globalDir: '.claude' },
-  codex: { template: 'codex.md', filename: 'AGENTS.md', globalDir: '.codex' },
-};
-
-const SUPPORTED = [...Object.keys(TARGETS), 'both'];
+const SUPPORTED = [...SUPPORTED_TARGETS, 'both'];
 
 export async function runInit(opts) {
   let raw = opts.target ? String(opts.target).toLowerCase() : '';
@@ -29,7 +23,7 @@ export async function runInit(opts) {
     throw new Error(`Unknown --target "${raw}". Supported: ${SUPPORTED.join(', ')}`);
   }
 
-  const targets = raw === 'both' ? ['claude', 'codex'] : [raw];
+  const targets = raw === 'both' ? [...SUPPORTED_TARGETS] : [raw];
   for (const t of targets) {
     await writeAgentRules(t, opts);
   }
@@ -53,12 +47,9 @@ async function chooseTarget() {
 
 async function writeAgentRules(target, opts) {
   const meta = TARGETS[target];
-  const templatePath = join(TEMPLATE_DIR, meta.template);
-  if (!existsSync(templatePath)) {
-    throw new Error(`Template not found for target "${target}" at ${templatePath}`);
-  }
-  const rawTemplate = readFileSync(templatePath, 'utf8');
-  const block = (await renderTemplate(rawTemplate, target)).trim();
+  // `init` writes the nano variant — the always-loaded block stays small.
+  // Full reference is on demand via `triss agent-help`.
+  const block = (await renderRules(target, { variant: 'nano' })).trim();
   const wrapped = `${START_MARKER}\n${block}\n${END_MARKER}\n`;
 
   const destPath = opts.global
@@ -140,48 +131,6 @@ async function postInit(opts) {
 // Re-export the helper for tests.
 export { postInit as _postInit };
 
-// Render the {{INTEGRATIONS}} placeholder. Two layers:
-//   1. If the MCP server is registered in Claude Code config, prepend a hint
-//      that the same operations are also available as native MCP tools so
-//      the agent prefers those.
-//   2. Splice in agentInstructions snippets from each integration whose
-//      required env vars are all set (so users who don't use Linear never
-//      see Linear instructions).
-async function renderTemplate(raw, target) {
-  if (!raw.includes('{{INTEGRATIONS}}')) return raw;
-  const integrations = await loadIntegrations();
-  const active = integrations.filter((m) => envReadiness(m).ready && m.agentInstructions?.[target]);
-
-  let mcpHint = '';
-  try {
-    const { present } = mcpStatus('global', { target });
-    if (present) {
-      const sessionLabel = target === 'codex' ? 'Codex' : 'Claude Code';
-      mcpHint =
-        `\n> 💡 **Triss is also available as MCP tools in this ${sessionLabel} session.**\n` +
-        '> Native tools — `triss_ask`, `triss_chat`, `triss_review`, `triss_jira_*`,\n' +
-        '> `triss_linear_*` etc. — are usually faster and have per-tool permissions.\n' +
-        '> Prefer them over the Bash invocations described below; the CLI block stays\n' +
-        '> as a fallback if MCP is not loaded.\n\n';
-    }
-  } catch {
-    /* config unreadable — silently fall back to CLI-only block */
-  }
-
-  let block;
-  if (!active.length && !mcpHint) {
-    block = '';
-  } else {
-    const integrationsBody = active.length
-      ? '\n## Integrations enabled for this project\n\n' +
-        active.map((m) => m.agentInstructions[target].trim()).join('\n\n') +
-        '\n\n'
-      : '';
-    block = mcpHint + integrationsBody;
-  }
-  return raw.replace(/\{\{INTEGRATIONS\}\}\n?/g, block);
-}
-
 function replaceBlock(text, replacement) {
   const start = text.indexOf(START_MARKER);
   const end = text.indexOf(END_MARKER, start);

package/src/config.js

@@ -1,7 +1,7 @@
 import dotenv from 'dotenv';
 import { activeEnvFiles } from './secrets.js';
 
-function loadEnvFiles() {
+export function loadEnvFiles() {
   // Precedence: process.env > project .triss.env > global ~/.config/triss/.env.
   // dotenv with override:false only fills *missing* keys, so the first call
   // (project) wins over the second (global), and real process env wins over

package/templates/claude-full.md

@@ -0,0 +1,151 @@
+## Triss — Cheap DeepSeek Coworker (Token Saving)
+
+You have a cheap DeepSeek-backed coworker available as the `triss` CLI on PATH.
+Use it to delegate token-heavy I/O so this conversation stays focused on
+reasoning, not on bulk reading, boilerplate, or tracker chatter.
+
+### `triss ask` — bulk reading
+Use instead of reading files yourself when:
+- a single file is >400 lines, or
+- you would otherwise read 3+ files to answer one question.
+
+```bash
+triss ask --paths <file1> <file2> ... --question "<specific question>"
+# heavier analysis:
+triss ask --paths src/**/*.ts --question "..." --model pro --max-tokens 16384
+```
+
+The worker returns a structured bullet summary with file paths and line
+numbers. Read the file yourself only when you need to make precise edits.
+
+### `triss write` — boilerplate generation
+Use for tests, config files, docstrings, repetitive code, or doc scaffolds.
+
+```bash
+triss write --spec "<what to write>" \
+            --context <existing-similar-file> \
+            --target <output-path>
+```
+
+After it writes, review the file and edit only what needs fixing.
+
+### `triss extract` — chat transcript extraction
+Pull a human-readable transcript out of Claude Code JSONL session logs.
+
+```bash
+triss extract ~/.claude/projects/<project>/<session>.jsonl -o /tmp/chat.txt
+```
+
+### `triss commit-msg` — generate a commit message from staged diff
+```bash
+git add <paths>
+triss commit-msg            # prints Conventional Commits message
+triss commit-msg --apply    # prints + runs `git commit -m`
+```
+
+Use this whenever the user asks you to commit work — much cheaper than
+the primary model writing the message itself, and the format is
+consistent.
+
+### `triss chat <prompt>` — bare worker prompt
+For one-shot lookups / transformations where there is **no corpus** —
+no files to read, no URLs to fetch, no diff to review. Just a question.
+
+```bash
+triss chat "что такое JWT в одном абзаце"
+triss chat "design a rate limiter for the auth endpoint" --model pro
+echo "long prompt..." | triss chat --stdin
+triss chat --system "ты Postgres эксперт" "explain MVCC"
+```
+
+Use it for trivial offload (definitions, rephrasings, ideation) so the
+primary model's tokens stay on actual code work. Do NOT use for code
+review (`triss review`), file analysis (`triss ask`), or anything that
+needs your reasoning.
+
+### `triss ask --stdin` — pipe any command into Triss
+**Universal escape hatch.** Anything that prints to stdout can be triaged
+via Triss without writing to a file first:
+
+```bash
+git diff main..HEAD     | triss ask --stdin --question "что критично изменилось?"
+git log --since=1.week  | triss ask --stdin --question "что я сделал на этой неделе?"
+kubectl logs my-pod     | triss ask --stdin --question "найди аномалии в логах"
+docker logs container 2>&1 | triss ask --stdin --question "errors and their causes"
+```
+
+Prefer this over reading the same output yourself when it's >2K tokens.
+
+### `triss review [PR]` — code review via DeepSeek
+For reviewing a branch or PR. Stitches together: the diff (git or `gh pr
+diff`), PR metadata (title + body if PR# given), and a linked Jira/Linear
+issue (auto-detected from `PROJ-NNN` keys in branch name or PR title).
+Defaults to the `pro` preset because review needs reasoning.
+
+```bash
+triss review                 # current branch vs auto-detected base
+triss review 123             # PR #123 in the current GitHub repo
+triss review --base develop  # HEAD vs develop
+triss review --skip-issue    # don't try to look up linked Jira/Linear ticket
+```
+
+**Use over reading diffs yourself** — token savings on diffs are usually
+10-20× since DeepSeek does the inspection and returns concrete bullets
+with file:line citations. If you still need to look at a specific file
+after the review, do so via Read.
+
+### `triss fetch` / `triss ask --urls` — web pages
+**Default to Triss for any web read. Use the built-in WebFetch tool only
+for the narrow case where you genuinely need raw markup** — e.g. extracting
+an exact regex/CSS-selector hit, copying a precise JSON shape, or you've
+already loaded the same URL in this session.
+
+You cannot tell whether a page is "short" until you've fetched it. Treat
+that as a non-decision: the rule is *who pays for the bytes*.
+
+| You want…                                | Use            | Why                                          |
+| ---------------------------------------- | -------------- | -------------------------------------------- |
+| Answer to a question about the page      | `triss fetch --question "…"` | DeepSeek pays for the body; you get ~300 tokens back |
+| Compare a page against local files       | `triss ask --urls … --paths …` | One round-trip, mixed corpus       |
+| Clean markdown on disk                   | `triss fetch <url> > /tmp/x.md` | No LLM at all                     |
+| Exact raw HTML / unprocessed text        | WebFetch       | Triss strips noise; you'd lose what you need |
+| Page already cached in this session      | WebFetch       | Re-fetching is wasted latency                |
+
+```bash
+# Default path — answer about the page
+triss fetch https://blog.example.com/post --question "what's the takeaway?"
+
+# Multi-URL corpus, mixed with local files
+triss ask --urls https://spec.example.com/v2 \
+          --paths README.md \
+          --question "what's missing from README that's in the spec?"
+
+# Just markdown, no LLM
+triss fetch https://api-docs.example.com/changelog
+```
+
+### Documentation workflow (preferred)
+**Do not write documentation from scratch in-context. Delegate the read.**
+
+1. `triss extract <latest-session.jsonl> -o /tmp/chat.txt`
+2. `triss ask --paths /tmp/chat.txt <doc-files> --question "read chat, give exact changes for docs"`
+3. Apply the worker's suggested edits via the Edit tool.
+
+### Models
+- `--model flash` (default) — cheap, fast, good for bulk reads.
+- `--model pro` — pricier, smarter, use for harder analysis or generation.
+- `--model <full-name>` — pin to any model id (e.g. `deepseek-v4-flash`).
+
+Override the preset names if needed via `TRISS_WORKER_FLASH_MODEL` and
+`TRISS_WORKER_PRO_MODEL` env vars (no code changes required).
+
+{{INTEGRATIONS}}
+### When NOT to delegate
+- Tasks under ~2000 tokens of work — delegation overhead costs more than it saves.
+- Architectural decisions, hard debugging, safety-critical code.
+- Anything requiring careful step-by-step reasoning you must own.
+- When you need exact line numbers to make a precise Edit — read the file yourself.
+
+Run `triss status` to verify the worker and any integrations are configured.
+Missing credentials? Suggest `triss config wizard` (or `triss config wizard <target>`
+for a single provider; `--local` saves to `./.triss.env` for project-only keys).

package/templates/claude.md

@@ -1,151 +1,17 @@
-## Triss — Cheap DeepSeek Coworker (Token Saving)
+## Triss — cheap delegation worker
 
-You have a cheap DeepSeek-backed coworker available as the `triss` CLI on PATH.
-Use it to delegate token-heavy I/O so this conversation stays focused on
-reasoning, not on bulk reading, boilerplate, or tracker chatter.
+You have a cheap DeepSeek-backed worker exposed as MCP tools (`triss_ask`,
+`triss_review`, `triss_fetch`, `triss_chat`, `triss_write`,
+`triss_commit_msg`, `triss_status`) — or the `triss` CLI as a fallback if
+MCP is not loaded.
 
-### `triss ask` — bulk reading
-Use instead of reading files yourself when:
-- a single file is >400 lines, or
-- you would otherwise read 3+ files to answer one question.
+**Delegate when:** a single file is >400 lines, you would otherwise read 3+
+files for one question, you need a code review of a diff, or you want the
+content of a web page (not raw HTML).
 
-```bash
-triss ask --paths <file1> <file2> ... --question "<specific question>"
-# heavier analysis:
-triss ask --paths src/**/*.ts --question "..." --model pro --max-tokens 16384
-```
+**Don't delegate when:** the task is <2k tokens, you need exact line numbers
+for an Edit, or it is an architectural / safety-critical decision you must
+reason through yourself.
 
-The worker returns a structured bullet summary with file paths and line
-numbers. Read the file yourself only when you need to make precise edits.
-
-### `triss write` — boilerplate generation
-Use for tests, config files, docstrings, repetitive code, or doc scaffolds.
-
-```bash
-triss write --spec "<what to write>" \
-            --context <existing-similar-file> \
-            --target <output-path>
-```
-
-After it writes, review the file and edit only what needs fixing.
-
-### `triss extract` — chat transcript extraction
-Pull a human-readable transcript out of Claude Code JSONL session logs.
-
-```bash
-triss extract ~/.claude/projects/<project>/<session>.jsonl -o /tmp/chat.txt
-```
-
-### `triss commit-msg` — generate a commit message from staged diff
-```bash
-git add <paths>
-triss commit-msg            # prints Conventional Commits message
-triss commit-msg --apply    # prints + runs `git commit -m`
-```
-
-Use this whenever the user asks you to commit work — much cheaper than
-the primary model writing the message itself, and the format is
-consistent.
-
-### `triss chat <prompt>` — bare worker prompt
-For one-shot lookups / transformations where there is **no corpus** —
-no files to read, no URLs to fetch, no diff to review. Just a question.
-
-```bash
-triss chat "что такое JWT в одном абзаце"
-triss chat "design a rate limiter for the auth endpoint" --model pro
-echo "long prompt..." | triss chat --stdin
-triss chat --system "ты Postgres эксперт" "explain MVCC"
-```
-
-Use it for trivial offload (definitions, rephrasings, ideation) so the
-primary model's tokens stay on actual code work. Do NOT use for code
-review (`triss review`), file analysis (`triss ask`), or anything that
-needs your reasoning.
-
-### `triss ask --stdin` — pipe any command into Triss
-**Universal escape hatch.** Anything that prints to stdout can be triaged
-via Triss without writing to a file first:
-
-```bash
-git diff main..HEAD     | triss ask --stdin --question "что критично изменилось?"
-git log --since=1.week  | triss ask --stdin --question "что я сделал на этой неделе?"
-kubectl logs my-pod     | triss ask --stdin --question "найди аномалии в логах"
-docker logs container 2>&1 | triss ask --stdin --question "errors and their causes"
-```
-
-Prefer this over reading the same output yourself when it's >2K tokens.
-
-### `triss review [PR]` — code review via DeepSeek
-For reviewing a branch or PR. Stitches together: the diff (git or `gh pr
-diff`), PR metadata (title + body if PR# given), and a linked Jira/Linear
-issue (auto-detected from `PROJ-NNN` keys in branch name or PR title).
-Defaults to the `pro` preset because review needs reasoning.
-
-```bash
-triss review                 # current branch vs auto-detected base
-triss review 123             # PR #123 in the current GitHub repo
-triss review --base develop  # HEAD vs develop
-triss review --skip-issue    # don't try to look up linked Jira/Linear ticket
-```
-
-**Use over reading diffs yourself** — token savings on diffs are usually
-10-20× since DeepSeek does the inspection and returns concrete bullets
-with file:line citations. If you still need to look at a specific file
-after the review, do so via Read.
-
-### `triss fetch` / `triss ask --urls` — web pages
-**Default to Triss for any web read. Use the built-in WebFetch tool only
-for the narrow case where you genuinely need raw markup** — e.g. extracting
-an exact regex/CSS-selector hit, copying a precise JSON shape, or you've
-already loaded the same URL in this session.
-
-You cannot tell whether a page is "short" until you've fetched it. Treat
-that as a non-decision: the rule is *who pays for the bytes*.
-
-| You want…                                | Use            | Why                                          |
-| ---------------------------------------- | -------------- | -------------------------------------------- |
-| Answer to a question about the page      | `triss fetch --question "…"` | DeepSeek pays for the body; you get ~300 tokens back |
-| Compare a page against local files       | `triss ask --urls … --paths …` | One round-trip, mixed corpus       |
-| Clean markdown on disk                   | `triss fetch <url> > /tmp/x.md` | No LLM at all                     |
-| Exact raw HTML / unprocessed text        | WebFetch       | Triss strips noise; you'd lose what you need |
-| Page already cached in this session      | WebFetch       | Re-fetching is wasted latency                |
-
-```bash
-# Default path — answer about the page
-triss fetch https://blog.example.com/post --question "what's the takeaway?"
-
-# Multi-URL corpus, mixed with local files
-triss ask --urls https://spec.example.com/v2 \
-          --paths README.md \
-          --question "what's missing from README that's in the spec?"
-
-# Just markdown, no LLM
-triss fetch https://api-docs.example.com/changelog
-```
-
-### Documentation workflow (preferred)
-**Do not write documentation from scratch in-context. Delegate the read.**
-
-1. `triss extract <latest-session.jsonl> -o /tmp/chat.txt`
-2. `triss ask --paths /tmp/chat.txt <doc-files> --question "read chat, give exact changes for docs"`
-3. Apply the worker's suggested edits via the Edit tool.
-
-### Models
-- `--model flash` (default) — cheap, fast, good for bulk reads.
-- `--model pro` — pricier, smarter, use for harder analysis or generation.
-- `--model <full-name>` — pin to any model id (e.g. `deepseek-v4-flash`).
-
-Override the preset names if needed via `TRISS_WORKER_FLASH_MODEL` and
-`TRISS_WORKER_PRO_MODEL` env vars (no code changes required).
-
-{{INTEGRATIONS}}
-### When NOT to delegate
-- Tasks under ~2000 tokens of work — delegation overhead costs more than it saves.
-- Architectural decisions, hard debugging, safety-critical code.
-- Anything requiring careful step-by-step reasoning you must own.
-- When you need exact line numbers to make a precise Edit — read the file yourself.
-
-Run `triss status` to verify the worker and any integrations are configured.
-Missing credentials? Suggest `triss config wizard` (or `triss config wizard <target>`
-for a single provider; `--local` saves to `./.triss.env` for project-only keys).
+For the full reference (examples, model presets, tracker integrations like
+Jira / Linear / GitHub) run `triss agent-help` once when you need it.

package/templates/codex-full.md

@@ -0,0 +1,51 @@
+# Triss — Cheap DeepSeek Coworker (Token Saving)
+
+You have a DeepSeek-backed worker available as the `triss` CLI on PATH.
+Delegate token-heavy I/O to it — the primary model's tokens stay on
+reasoning and edits.
+
+## Commands
+
+| Command | Use for |
+| --- | --- |
+| `triss ask --paths <files> --question "<q>"` | bulk read of files; structured summary back |
+| `triss ask --urls <url> --question "<q>"` | same for web pages (HTML→markdown internally) |
+| `triss ask --stdin --question "<q>"` | pipe any command's stdout (`git diff \| triss ask --stdin -q "..."`) |
+| `triss chat "<prompt>"` | bare worker prompt, no corpus — definitions, transformations |
+| `triss write --spec "<spec>" --context <ref> --target <out>` | boilerplate generation against a style reference |
+| `triss extract <session.jsonl> -o <out>` | extract human-readable transcript from Claude Code logs |
+| `triss fetch <url> [--question "<q>"]` | fetch URL → markdown (with `--question`, summary) |
+| `triss review [<pr>]` | code review on current branch or a GitHub PR (auto-detects linked Jira/Linear ticket) |
+| `triss commit-msg [--apply]` | Conventional Commits message from staged diff |
+| `triss usage [--since 7d \| --month] [--by-project]` | cumulative cost / token report |
+| `triss status` | model + integration readiness |
+
+## When to delegate
+
+Delegate any read >400 lines or 3+ files for one question, any web fetch,
+any code review on a real diff. Delegate boilerplate generation against a
+reference. Do **not** delegate:
+
+- architectural decisions or hard debugging,
+- edits that need exact line numbers (use direct read/edit instead),
+- tasks under ~2000 tokens (delegation overhead costs more).
+
+## Models
+
+Default preset is `flash` (cheap). Use `--model pro` for harder analysis
+or code review. Override preset names via `TRISS_WORKER_FLASH_MODEL` /
+`TRISS_WORKER_PRO_MODEL`. Pick a default with `TRISS_DEFAULT_MODEL=flash|pro`.
+
+## Tracker integrations
+
+`triss jira / linear / github / gitlab / confluence` expose `search`,
+`issue`/`page`, `create`, `update`, `comment`. Each subcommand accepts
+`--question "<q>"` to summarise via DeepSeek instead of dumping raw API
+output. Configure with `triss config wizard <name>`.
+
+{{INTEGRATIONS}}
+
+Run `triss status` to verify. Missing credentials? Run
+`triss config wizard` for an interactive setup, or
+`triss config wizard <target>` for one provider. Add `--local` to scope
+to `./.triss.env` instead of the global file.

package/templates/codex.md

@@ -1,51 +1,18 @@
-# Triss — Cheap DeepSeek Coworker (Token Saving)
+# Triss — cheap delegation worker
 
-You have a DeepSeek-backed worker available as the `triss` CLI on PATH.
-Delegate token-heavy I/O to it — the primary model's tokens stay on
-reasoning and edits.
+You have a cheap DeepSeek-backed worker exposed as MCP tools (`triss_ask`,
+`triss_review`, `triss_fetch`, `triss_chat`, `triss_write`,
+`triss_commit_msg`, `triss_status`) — or the `triss` CLI as a fallback if
+MCP is not loaded.
 
-## Commands
+**Delegate when:** a single file is >400 lines, you would otherwise read 3+
+files for one question, you need a code review of a diff, or you want the
+content of a web page (not raw HTML).
 
-| Command | Use for |
-| --- | --- |
-| `triss ask --paths <files> --question "<q>"` | bulk read of files; structured summary back |
-| `triss ask --urls <url> --question "<q>"` | same for web pages (HTML→markdown internally) |
-| `triss ask --stdin --question "<q>"` | pipe any command's stdout (`git diff \| triss ask --stdin -q "..."`) |
-| `triss chat "<prompt>"` | bare worker prompt, no corpus — definitions, transformations |
-| `triss write --spec "<spec>" --context <ref> --target <out>` | boilerplate generation against a style reference |
-| `triss extract <session.jsonl> -o <out>` | extract human-readable transcript from Claude Code logs |
-| `triss fetch <url> [--question "<q>"]` | fetch URL → markdown (with `--question`, summary) |
-| `triss review [<pr>]` | code review on current branch or a GitHub PR (auto-detects linked Jira/Linear ticket) |
-| `triss commit-msg [--apply]` | Conventional Commits message from staged diff |
-| `triss usage [--since 7d \| --month] [--by-project]` | cumulative cost / token report |
-| `triss status` | model + integration readiness |
+**Don't delegate when:** the task is <2k tokens, you need exact line numbers
+for an Edit, or it is an architectural / safety-critical decision you must
+reason through yourself.
 
-## When to delegate
-
-Delegate any read >400 lines or 3+ files for one question, any web fetch,
-any code review on a real diff. Delegate boilerplate generation against a
-reference. Do **not** delegate:
-
-- architectural decisions or hard debugging,
-- edits that need exact line numbers (use direct read/edit instead),
-- tasks under ~2000 tokens (delegation overhead costs more).
-
-## Models
-
-Default preset is `flash` (cheap). Use `--model pro` for harder analysis
-or code review. Override preset names via `TRISS_WORKER_FLASH_MODEL` /
-`TRISS_WORKER_PRO_MODEL`. Pick a default with `TRISS_DEFAULT_MODEL=flash|pro`.
-
-## Tracker integrations
-
-`triss jira / linear / github / gitlab / confluence` expose `search`,
-`issue`/`page`, `create`, `update`, `comment`. Each subcommand accepts
-`--question "<q>"` to summarise via DeepSeek instead of dumping raw API
-output. Configure with `triss config wizard <name>`.
-
-{{INTEGRATIONS}}
-
-Run `triss status` to verify. Missing credentials? Run
-`triss config wizard` for an interactive setup, or
-`triss config wizard <target>` for one provider. Add `--local` to scope
-to `./.triss.env` instead of the global file.
+For the full reference (examples, model presets, tracker integrations like
+Jira / Linear / GitHub) run `triss agent-help --target codex` once when you
+need it.