@sayknow-cli/coding-agent 0.7.9 → 0.7.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/dist/types/config/settings-schema.d.ts +9 -0
- package/dist/types/tools/gitlab.d.ts +128 -0
- package/dist/types/tools/index.d.ts +1 -0
- package/dist/types/utils/git.d.ts +21 -0
- package/package.json +7 -7
- package/src/cli/args.ts +12 -18
- package/src/config/settings-schema.ts +11 -0
- package/src/i18n/messages/de.settings.ts +3 -0
- package/src/i18n/messages/es.settings.ts +3 -0
- package/src/i18n/messages/fr.settings.ts +3 -0
- package/src/i18n/messages/ja.settings.ts +3 -0
- package/src/i18n/messages/ko.settings.ts +3 -0
- package/src/i18n/messages/zh.settings.ts +2 -0
- package/src/internal-urls/docs-index.generated.ts +9 -7
- package/src/prompts/tools/gitlab.md +13 -0
- package/src/sdk/session.ts +12 -1
- package/src/tools/gitlab.ts +355 -0
- package/src/tools/index.ts +4 -0
- package/src/utils/git.ts +128 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT
|
|
2
2
|
Reflect.set(globalThis, Symbol.for("skc.docs-index.generated.loaded"), true);
|
|
3
3
|
|
|
4
|
-
export const EMBEDDED_DOC_FILENAMES: readonly string[] = ["ERRATA-GPT5-HARMONY.md","REBRANDING_PLAN_260525.md","adr-inline-selection-gate.md","adr-overlay-component-seam.md","adr-sessions-dashboard.md","ai-schema-normalize.md","analyze-me-with-skc.md","aside-integration.md","auth-broker-gateway.md","bash-tool-runtime.md","blob-artifact-architecture.md","bot-integration.md","brand-assets.md","bridge.md","codebase-overview.md","codegraph-custom-tool.md","compaction.md","composer-codex-parity.md","computer-use/README.md","discord-onboarding.md","environment-variables.md","external-control-readiness.md","extragoal-skill-template.md","fs-scan-cache-architecture.md","geobench.md","git-daemon.md","gpt-5.6-codex-preset-benchmark.md","grok-build-provider-design.md","handoff-generation-pipeline.md","hermes-mcp-bridge.md","hotspot-map-successor.md","keybindings.md","lsp-config.md","memory.md","models.md","multi-vendor-profiles.md","native-ffi-optimization-policy.md","natives-addon-loader-runtime.md","natives-architecture.md","natives-binding-contract.md","natives-build-release-debugging.md","natives-media-system-utils.md","natives-package-split-plan.md","natives-rust-task-cancellation.md","natives-shell-pty-process.md","natives-text-search-pipeline.md","non-compaction-retry-policy.md","notebook-tool-runtime.md","notifications-sdk.md","onboarding-packet.md","onboarding-receipt.md","ooo-bridge-extension-contract.md","openclaw-hermes-rpc-integration.md","perf-profiling-corpus.md","porting-from-pi-mono.md","porting-to-natives.md","prompt-architect-reports/README.md","prompt-architect-reports/recovered-context/0-ToolPrompts.recovered.md","prompt-architect-reports/recovered-context/1-SystemPrompts.recovered.md","prompt-architect-reports/recovered-context/3-SkillMiscPrompts.recovered.md","prompt-architect-reports/recovery-summary.md","prompt-architect-reports/system-prompts.raw.md","prompt-architect-reports/tool-prompts.raw.md","provider-streaming-internals.md","python-repl.md","readme/README.de.md","readme/README.es.md","readme/README.fr.md","readme/README.ja.md","readme/README.ko.md","readme/README.zh.md","render-mermaid.md","research-plan-ledger.md","resolve-tool-runtime.md","rpc.md","rulebook-matching-pipeline.md","sayknow-remote.md","sdk-app-guide.md","sdk-embedding.md","sdk-rpc-parity-audit.md","sdk.md","secrets.md","session-import.md","session-operations-export-share-fork-resume.md","session-switching-and-recent-listing.md","session-tree-plan.md","session.md","skc-dogfood-skill-template.md","skc-plugins.md","skc-session-clawhip-routing.md","slack-onboarding.md","standalone-mcp.md","telegram-onboarding.md","telegram-remote.md","telegram-session-close-timeout-bug.md","theme.md","tools/ask.md","tools/ast-edit.md","tools/ast-grep.md","tools/bash.md","tools/bisect.md","tools/browser.md","tools/calc.md","tools/checkpoint.md","tools/computer.md","tools/cron.md","tools/debug.md","tools/edit.md","tools/eval.md","tools/find.md","tools/github.md","tools/irc.md","tools/job.md","tools/locate.md","tools/lsp.md","tools/monitor.md","tools/read.md","tools/recipe.md","tools/render_mermaid.md","tools/resolve.md","tools/rewind.md","tools/search.md","tools/search_tool_bm25.md","tools/ssh.md","tools/task.md","tools/todo_write.md","tools/web_search.md","tools/write.md","tree.md","ttsr-injection-lifecycle.md","tui-runtime-internals.md","ui-design-visual-qa.md"];
|
|
4
|
+
export const EMBEDDED_DOC_FILENAMES: readonly string[] = ["ERRATA-GPT5-HARMONY.md","REBRANDING_PLAN_260525.md","adr-inline-selection-gate.md","adr-overlay-component-seam.md","adr-sessions-dashboard.md","ai-schema-normalize.md","analyze-me-with-skc.md","aside-integration.md","auth-broker-gateway.md","bash-tool-runtime.md","blob-artifact-architecture.md","bot-integration.md","brand-assets.md","bridge.md","codebase-overview.md","codegraph-custom-tool.md","compaction.md","composer-codex-parity.md","computer-use/README.md","discord-onboarding.md","environment-variables.md","external-control-readiness.md","extragoal-skill-template.md","fs-scan-cache-architecture.md","geobench.md","git-daemon.md","gpt-5.6-codex-preset-benchmark.md","grok-build-provider-design.md","handoff-generation-pipeline.md","hermes-mcp-bridge.md","hotspot-map-successor.md","keybindings.md","lsp-config.md","memory.md","messenger-initiated-sessions.md","models.md","multi-vendor-profiles.md","native-ffi-optimization-policy.md","natives-addon-loader-runtime.md","natives-architecture.md","natives-binding-contract.md","natives-build-release-debugging.md","natives-media-system-utils.md","natives-package-split-plan.md","natives-rust-task-cancellation.md","natives-shell-pty-process.md","natives-text-search-pipeline.md","non-compaction-retry-policy.md","notebook-tool-runtime.md","notifications-sdk.md","onboarding-packet.md","onboarding-receipt.md","ooo-bridge-extension-contract.md","openclaw-hermes-rpc-integration.md","perf-profiling-corpus.md","porting-from-pi-mono.md","porting-to-natives.md","prompt-architect-reports/README.md","prompt-architect-reports/recovered-context/0-ToolPrompts.recovered.md","prompt-architect-reports/recovered-context/1-SystemPrompts.recovered.md","prompt-architect-reports/recovered-context/3-SkillMiscPrompts.recovered.md","prompt-architect-reports/recovery-summary.md","prompt-architect-reports/system-prompts.raw.md","prompt-architect-reports/tool-prompts.raw.md","provider-streaming-internals.md","python-repl.md","readme/README.de.md","readme/README.es.md","readme/README.fr.md","readme/README.ja.md","readme/README.ko.md","readme/README.zh.md","render-mermaid.md","research-plan-ledger.md","resolve-tool-runtime.md","rpc.md","rulebook-matching-pipeline.md","sayknow-remote.md","sdk-app-guide.md","sdk-embedding.md","sdk-rpc-parity-audit.md","sdk.md","secrets.md","session-import.md","session-operations-export-share-fork-resume.md","session-switching-and-recent-listing.md","session-tree-plan.md","session.md","skc-dogfood-skill-template.md","skc-plugins.md","skc-session-clawhip-routing.md","slack-onboarding.md","standalone-mcp.md","telegram-onboarding.md","telegram-remote.md","telegram-session-close-timeout-bug.md","theme.md","tools/ask.md","tools/ast-edit.md","tools/ast-grep.md","tools/bash.md","tools/bisect.md","tools/browser.md","tools/calc.md","tools/checkpoint.md","tools/computer.md","tools/cron.md","tools/debug.md","tools/edit.md","tools/eval.md","tools/find.md","tools/github.md","tools/gitlab.md","tools/irc.md","tools/job.md","tools/locate.md","tools/lsp.md","tools/monitor.md","tools/read.md","tools/recipe.md","tools/render_mermaid.md","tools/resolve.md","tools/rewind.md","tools/search.md","tools/search_tool_bm25.md","tools/ssh.md","tools/task.md","tools/todo_write.md","tools/web_search.md","tools/write.md","tree.md","ttsr-injection-lifecycle.md","tui-runtime-internals.md","ui-design-visual-qa.md"];
|
|
5
5
|
|
|
6
6
|
export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
|
|
7
7
|
"ERRATA-GPT5-HARMONY.md": "# ERRATA — GPT-5 Harmony-Header Leakage\n\n## 1. The problem\n\nOpenAI frames tool calls in the Harmony chat protocol:\n\n```\n<|start|>assistant<|channel|>commentary to=functions.<NAME><|message|>{ARGS}<|call|>\n```\n\n`<|channel|>commentary to=functions.NAME` is the **routing header** —\ncontrol tokens consumed by the runtime to dispatch the call. These\ntokens never appear as content under normal operation; the runtime\nstrips them.\n\nThe defect: gpt-5 models occasionally emit, **as ordinary content\ninside `{ARGS}`**, the **plain-text shadow** of these routing tokens —\nthe same characters without the `<|…|>` brackets — and continue\nproducing more pseudo-routing structure (channel name, body marker,\nmultilingual spam, fake tool-result framing). The contamination lives\ninside the visible tool argument and is dispatched to the tool as if it\nwere intended content.\n\n**Critical detail.** The actual `<|start|>` / `<|channel|>` /\n`<|message|>` / `<|call|>` special tokens almost never appear in tool\nargs. What leaks is the bracket-less spelling — `analysis to=functions.X\ncode …` — because OpenAI applies a logit mask suppressing the\ncontrol-token IDs inside the args region. The mass that would have gone\nto those special tokens redistributes onto the un-bracketed plain-text\nrepresentation the model also learned. This makes the leak structurally\ninvisible to the routing parser and lands it in the tool input verbatim.\n\nManifestation in tool args (real corpus example):\n\n```\n~ add_function(iso, ctx, ns, \"installSystemChangeObserver\",\n os_install_system_change_observer);】【\"】【analysis to=functions.edit\n code above เงินไทยฟรีuser to=functions.edit code …\n```\n\nThe leading code is real and intended. Everything after the first\nnon-Latin token through the next clean structural boundary is corruption.\n\n---\n\n## 2. Observed statistics & failure modes\n\nSource: `~/.skc/stats.db` (`ss_tool_calls`, `ss_assistant_msgs`), through\n2026-05-10. 1.05M tool calls scanned.\n\n### 2.1 Rate\n\n| Model | Leaks in tool args | Calls | per million |\n|------------------|-------------------:|--------:|------------:|\n| gpt-5.4 | 37 | 226,957 | 163 |\n| gpt-5.3-openai-code | 17 | 112,243 | 151 |\n| gpt-5.5 | 2 | 80,750 | 25 |\n| gpt-5.2-openai-code | 0 | — | — |\n\nPlus 15 hits in assistant visible text / thinking blobs.\n\n### 2.2 Tool distribution\n\n| Tool | Hits |\n|---------------------|-----:|\n| `edit` | 38 |\n| `eval` | 11 |\n| `report_tool_issue` | 3 |\n| `grep`/`read`/`search`/`yield` | 1 each |\n\nConcentrated in tools with free-form (non-JSON-schema) argument formats.\n\n### 2.3 Leak shape (deterministic)\n\n```\nLEAK ::= JUNK_PREFIX MARKER CHANNEL_BODY (LEAK)?\nMARKER ::= \"to=functions.\" TOOL_NAME\nCHANNEL_BODY ::= \" code \" (SPAM | reasoning_prose | fake_tool_output)*\nJUNK_PREFIX ::= (GLITCH_TOKEN | CHANNEL_WORD | NON_LATIN_RUN | \"}\" | \"】【\")+\n```\n\n**Cascading is common.** Of 96 marker occurrences across 71 contaminated\nrecords, 39 contain ≥2 markers and 7 contain ≥3 — the model emits\nmultiple fake `to=functions.X code …` blocks back-to-back, often with\nfake `code_output\\nCell N:\\n…` framing between them. Once the\nplain-text scaffolding is in the residual stream, the prefix now *looks\nlike* a fresh tool envelope start, so the macro prior over continuations\nkeeps voting for more scaffolding. Self-amplifying.\n\n### 2.4 Glitch tokens\n\nSingle-token identifiers in `o200k_base` whose embeddings appear to be\nnear-init from underrepresentation in post-training. ASCII residue\nimmediately before the marker in the natural corpus:\n\n| Surface string | Single-token | Token ID | Hits in corpus |\n|-------------------|:-:|---------:|---:|\n| `Japgolly` | ✅ | 199,745 | 1 |\n| `Jsii` | ✅ | 114,318 | (subtoken of `Jsii_commentary`) |\n| `Jsii_commentary` | — (3 toks) | — | 2 |\n| `changedFiles` | — (2 toks) | — | 8 |\n| `RTLU` | — (2 toks) | — | 3 |\n\n`Japgolly` is in the last 0.13% of the vocabulary — the same family of\nGitHub-corpus residue that produced `SolidGoldMagikarp` in the 2023\nGPT-2 vocabulary (Rumbelow & Watkins). `SolidGoldMagikarp` itself\ntokenizes to 5 tokens in `o200k_base` — that specific token was retired,\nbut the class wasn't.\n\nFor the multi-token entries, the corpus-level signature is the surface\nstring; the underlying glitch trigger is a sub-token (e.g. `Jsii` inside\n`Jsii_commentary`). The detector list (`G` signal) keys on the surface\nstrings.\n\nStable across unrelated sessions. Treated as a high-precision detector\nsignal.\n\n### 2.5 Channel-word leakage\n\n`analysis` (5), `assistant` (5), `commentary` (3), `user` (1) appear\ndirectly preceding `to=`. Always bare words; never `<|channel|>analysis`\nor any other bracketed form. Consistent with §1 — the brackets are\nmasked, the words are not.\n\n### 2.6 Non-Latin spam residue\n\n96 marker hits, by script: CJK 40, Cyrillic 12, Telugu/Kannada/Malayalam\n18, Thai 8, Georgian 7, Armenian 7, Arabic 1. Recurring fragments are\nChinese gambling SEO (`大发时时彩`, `天天中彩票`), Georgian/Abkhaz junk,\nand Thai casino spam — well-known low-quality crawl residue.\n\nThis is the same script distribution observed in the controlled\nreproduction (§7.3), independent of the prompt's natural language.\n\n### 2.7 Failure-mode breakdown for the `edit` tool\n\nThe `edit` tool exists in two variants in the corpus:\n\n| Variant | Calls | Recovery |\n|--------------------------|------:|----------|\n| Patch-DSL (`§PATH`/anchor/`«»≔` ops) | 27 | **Recoverable** by op-truncation (§3.3) |\n| JSON-schema (`{path,edits:[…]}`) | 11 | **Not recoverable** — contamination is escaped *inside* JSON strings, parser accepts it cleanly, content would be written verbatim into source files |\n\nFor Patch-DSL leaks specifically:\n\n- 20/27 cases: contamination on the last input line; nothing follows.\n- 7/27 cases: contamination mid-input; what follows is one of: a\n duplicate replay of an earlier file/anchor, intended content for a\n *different* tool call (the model started its next call inline), or\n pure hallucination. Post-contamination content is never trustworthy.\n\n### 2.8 Mechanism (confirmed)\n\n**Prior collapse from null-embedding glitch tokens, into a\ncontrol-token-masked basin whose mass redistributes onto the\nplain-text shadow of the Harmony protocol.**\n\nStep by step:\n\n1. The model is mid-`{ARGS}` of a Harmony tool call. The runtime applies\n a logit mask suppressing structural control tokens (`<|channel|>`,\n `<|message|>`, `<|call|>`, `<|start|>`, `<|end|>`) inside the args\n region. Without this mask, normal generation would constantly\n hallucinate envelope-closes; with it, those token IDs have logit\n `-∞` in args.\n2. A glitch token `g` is sampled. By construction `g` was in the BPE\n merge corpus but barely in LM/RL training, so its **input embedding\n `e_g` ≈ near-init noise of small norm**.\n3. At position t+1, the residual update `h_{t+1} ≈ LN(h_t + e_g + Attn +\n MLP)` is dominated by the prefix-derived terms; the just-emitted-token\n signal is effectively absent. Generation diversity normally comes\n from `e_x` steering the residual into different sub-regions —\n stripped here.\n4. The next-token distribution therefore collapses onto the **conditional\n prior over continuations of the prefix, with local conditioning\n removed**. In a tool-calling rollout context, that prior is sharply\n peaked on Harmony scaffolding (control tokens + routing tokens) —\n that's what RL trained.\n5. The mask zeros the control-token IDs. Mass redistributes onto the\n **next-best continuation**: the un-bracketed surface-form spelling of\n the same protocol (`analysis`, `commentary`, ` to=functions.X`,\n ` code `). This spelling is unmasked because those characters are\n ordinary tokens.\n6. Once a few tokens of plain-text scaffolding land in the residual\n stream, the prefix now resembles a fresh envelope start. The macro\n prior keeps voting for more scaffolding. Cascading (§2.3) follows.\n7. Multilingual spam after the marker is the same prior-collapse\n continuation, drawn from the training neighborhood of the glitch\n token (often ESL/auto-generated multilingual web junk — exactly the\n crawl residue in §2.6).\n\n**Two corollaries the corpus data demanded but only the experiment\nexplained:**\n\n- **The brackets never appear** (§1, §2.5). The mask is what makes the\n leak land in plain text instead of as a real envelope-close.\n- **Counterintuitive grammar dependency** (§7.4). The leak is *worse* in\n formats closest to OpenAI's training distribution. Off-distribution\n custom grammars dampen the macro-prior basin; the official\n `*** Begin Patch` format is the strongest collapse target.\n\nThe 2023 SolidGoldMagikarp paper documented mechanism (1)+(2)+(4). The\nnew piece is (5): when constrained decoding masks the natural collapse\ntarget, the mass laundered through the un-masked plain-text shadow\nbecomes a structurally-invisible exfiltration channel.",
|
|
@@ -38,6 +38,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
|
|
|
38
38
|
"keybindings.md": "# Keybindings\n\nRun `/hotkeys` inside an `skc` session to see the active chords for your current build. The list reflects any remaps loaded from disk and any bindings added by extensions.\n\n## Customize keybindings\n\nUser remaps live in `~/.skc/agent/keybindings.json`. The file is a JSON object whose keys are keybinding action IDs and whose values are either one chord string or an array of chord strings. It is not read from `~/.skc/agent/config.yml`, and there is no nested `keybindings` object.\n\n```json\n{\n \"app.commandPalette.open\": \"ctrl+p\",\n \"app.model.cycleForward\": \"alt+n\",\n \"app.model.selectTemporary\": \"alt+p\",\n \"app.plan.toggle\": \"alt+shift+p\"\n}\n```\n\nChord names are case-insensitive. New configuration should use canonical textual IDs rather than matching the labels shown in the UI.\nConfiguration uses portable canonical key IDs, not the labels printed by a particular host: use `ctrl`, `alt`, `shift`, and `super` with a key name, for example `ctrl+p`, `alt+enter`, `shift+tab`, and `super+c`. Matching is case-insensitive, but new configuration should use this canonical textual form so the same file remains portable.\n\nRuntime UI labels are platform-native. On macOS, `Ctrl`, `Alt`, `Shift`, and `Super` display as `⌃`, `⌥`, `⇧`, and `⌘`; MacBook keycaps such as Return, Escape, Tab, Delete, and the arrow keys display as `↩`, `⎋`, `⇥`, `⌫`/`⌦`, and arrows. These glyphs are display labels only: configure `super+c`, not `⌘C`, and `alt+enter`, not `⌥↩`.\nOn macOS, Option shortcuts work only when the terminal sends Option as Meta/Esc or uses an enhanced keyboard protocol that reports the modifier. Command/Super is usually handled by the terminal or operating system and does not reach SKC. Windows Alt and macOS Option both use the canonical `alt` ID in configuration. Text produced by an Option key as composed Unicode cannot be reverse-inferred as an Option chord.\n\nFor terminals that do not forward Option, remap the queue actions to canonical Control chords (choose unclaimed chords appropriate for your terminal), for example:\n\n```json\n{\n \"app.message.queue\": \"ctrl+q\",\n \"app.message.dequeue\": [\"ctrl+pageup\", \"ctrl+pagedown\"]\n}\n```\nStatic onboarding and generated reference material describe shipped defaults and must stay host-independent. The active runtime surface is authoritative for effective bindings after user remaps and extensions load: use `/hotkeys` to see those bindings on the current platform.\n\nSet an action to an empty array to disable it:\n\n```json\n{\n \"app.stt.toggle\": []\n}\n```\n\n## Common action IDs\n\n| Action ID | Default | Meaning |\n| --- | --- | --- |\n| `app.commandPalette.open` | `ctrl+p` | Open the command palette |\n| `app.model.cycleForward` | `alt+n` | Cycle role models forward |\n| `app.model.cycleBackward` | `alt+shift+n` | Cycle role models backward |\n| `app.model.selectTemporary` | `alt+p` | Pick a model temporarily for this session |\n| `app.model.select` | `ctrl+l` | Open the model selector and set roles |\n| `app.plan.toggle` | `alt+shift+p` | Toggle plan mode |\n| `app.history.search` | `ctrl+r` | Search prompt history |\n| `app.tools.expand` | `ctrl+o` | Toggle tool-output expansion |\n| `app.thinking.toggle` | `ctrl+t` | Toggle thinking-block visibility |\n| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |\n| `app.editor.external` | `ctrl+g` | Edit the draft in `$VISUAL` / `$EDITOR` |\n| `app.message.followUp` | _(none)_ | Optional remap for a follow-up message; `ctrl+enter` is reserved for editor newline |\n| `app.message.queue` | `alt+enter` (`alt+q` on darwin/win32) | Explicitly queue a message for the next turn |\n| `app.message.dequeue` | `alt+up`, `alt+down` | Open the queue and select a queued message to edit |\n\n| `app.clipboard.copyLine` | `alt+shift+l` | Copy the current line |\n| `app.clipboard.copyPrompt` | `alt+shift+c` | Copy the whole prompt |\n| `app.stt.toggle` | `alt+h` | Toggle speech-to-text recording |\n| `app.irc.sidebar.toggle` | `alt+i` | Toggle IRC sidebar |\n\nOlder unqualified action names are migrated when `keybindings.json` is loaded, but new docs and new configs should use the namespaced action IDs above.\n\nOn macOS, Option+Q queues a message for the next turn; on native Windows terminals, the equivalent default is Alt+Q. Windows Terminal and PowerShell commonly reserve Alt+Enter for fullscreen before SKC can receive it. Users who prefer another chord can remap `app.message.queue` in `~/.skc/agent/keybindings.json`.\n\nWhen messages are queued, use Option+Up/Down on macOS (Alt+Up/Down on Windows) to open the queue and select a message. In the queue, Return edits the selected message, Forward Delete (`⌦`; Fn+Delete on compact Mac keyboards) removes it, Control+Up/Down reorders it within its delivery group, and Escape closes the queue. Reordering does not convert compaction, steer, and follow-up messages into one another.\n\nIn the main SKC composer, plain `PageUp` / `PageDown` page the visible transcript lane instead of browsing prompt history; the status line and composer remain fixed at the bottom while manually scrolled. When SKC owns mouse input (`mouse.enabled: true`), the wheel moves the transcript by three rows per notch. Ordinary typing or paste keeps editor focus and returns to live output before editing; use `Up` / `Down` or `Ctrl+R` for prompt history. Autocomplete and selector surfaces still use `PageUp` / `PageDown` for list paging while they have focus.\n\n## Auditing default-key collisions\n\nSome default chords are intentionally reused across different UI contexts, where the focused component disambiguates them at dispatch time. For example `Enter` maps to both input submit and selection confirm, and `Ctrl+C` maps to both input copy and selection cancel. These are not conflicts — only one context is active at a time.\n\nTo audit the registry for keys whose default binding is claimed by more than one action, use `detectDefaultKeyCollisions(definitions)` from `@sayknow-cli/tui/keybindings`. It returns one entry per colliding key with the list of claiming action IDs, which is useful when adding new defaults or reviewing the surface. User-remap conflicts (multiple actions bound to the same chord in `keybindings.json`) continue to be reported separately by `KeybindingsManager.getConflicts()`.\n\nTwo audit clarifications for the current surface:\n\n- `app.clipboard.copyLine` is registry-backed and dispatched through the input controller's custom key handlers, not hardcoded.\n- `tui.input.copy` is declared in the registry but is not currently dispatched by `Editor.handleInput`.\n\nThe editor's configurable action defaults (including the platform-aware `app.clipboard.pasteImage` default) are derived directly from the central `KEYBINDINGS` registry, so there is a single source of truth for those defaults.\n\n## Current surface audit\n\nAuthoritative inventory of the keybinding registry, one row per action. Generated from `TUI_KEYBINDINGS` (`packages/tui/src/keybindings.ts`) and `KEYBINDINGS` (`packages/coding-agent/src/config/keybindings.ts`). Every action ID below is remappable via `~/.skc/agent/keybindings.json` unless noted. A drift test (`packages/coding-agent/test/keybindings-audit.test.ts`) asserts every registry action ID appears in this table.\n\n### Editor context (`tui.editor.*`)\n\n| Action ID | Default | Notes |\n| --- | --- | --- |\n| `tui.editor.cursorUp` | `up` | |\n| `tui.editor.cursorDown` | `down` | |\n| `tui.editor.cursorLeft` | `left`, `ctrl+b` | `ctrl+b` also `app.tool.backgroundFold` (other context) |\n| `tui.editor.cursorRight` | `right`, `ctrl+f` | |\n| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | `ctrl+left` also `app.tree.foldOrUp` |\n| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | `ctrl+right` also `app.tree.unfoldOrDown` |\n| `tui.editor.cursorLineStart` | `home`, `ctrl+a` | |\n| `tui.editor.cursorLineEnd` | `end`, `ctrl+e` | |\n| `tui.editor.jumpForward` | `ctrl+]` | |\n| `tui.editor.jumpBackward` | `ctrl+alt+]` | |\n| `tui.editor.pageUp` | `pageUp` | |\n| `tui.editor.pageDown` | `pageDown` | |\n| `tui.editor.deleteCharBackward` | `backspace` | |\n| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | `ctrl+d` also `app.exit` / `app.session.delete` |\n| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace`, `ctrl+backspace` | |\n| `tui.editor.deleteWordForward` | `alt+delete`, `alt+d` | |\n| `tui.editor.deleteToLineStart` | `ctrl+u` | |\n| `tui.editor.deleteToLineEnd` | `ctrl+k` | |\n| `tui.editor.yank` | `ctrl+y` | |\n| `tui.editor.yankPop` | `alt+y` | |\n| `tui.editor.undo` | `ctrl+-`, `ctrl+_` | |\n\n### Input context (`tui.input.*`)\n\n| Action ID | Default | Notes |\n| --- | --- | --- |\n| `tui.input.newLine` | `Shift+Enter` | `Ctrl+Enter` and `Ctrl+Shift+Enter` are also accepted by the editor when the terminal encodes them distinctly |\n\n| `tui.input.submit` | `enter` | also `tui.select.confirm` (other context) |\n| `tui.input.tab` | `tab` | |\n| `tui.input.copy` | `ctrl+c` | declared but not dispatched by `Editor.handleInput` |\n\n### Selection context (`tui.select.*`)\n\n| Action ID | Default | Notes |\n| --- | --- | --- |\n| `tui.select.up` | `up` | |\n| `tui.select.down` | `down` | |\n| `tui.select.pageUp` | `pageUp` | |\n| `tui.select.pageDown` | `pageDown` | |\n| `tui.select.confirm` | `enter` | |\n| `tui.select.cancel` | `escape`, `ctrl+c` | `escape` also `app.interrupt` |\n\n### Application context (`app.*`)\n\n| Action ID | Default | Domains |\n| --- | --- | --- |\n| `app.interrupt` | escape | global |\n| `app.clear` | ctrl+c | global |\n| `app.exit` | ctrl+d | global |\n| `app.suspend` | ctrl+z | global |\n| `app.thinking.cycle` | shift+tab | composer |\n| `app.thinking.toggle` | ctrl+t | composer |\n| `app.commandPalette.open` | ctrl+p | composer |\n| `app.model.cycleForward` | alt+n | composer |\n| `app.model.cycleBackward` | alt+shift+n | composer |\n| `app.model.select` | ctrl+l | composer |\n| `app.model.selectTemporary` | alt+p | composer |\n| `app.tools.expand` | ctrl+o | composer |\n| `app.todo.toggle` | alt+shift+t | composer |\n| `app.tool.backgroundFold` | ctrl+b | composer |\n| `app.editor.external` | ctrl+g | composer |\n| `app.message.followUp` | _(none)_ | composer |\n| `app.message.queue` | alt+q (darwin/win32) / alt+enter (linux) | composer |\n| `app.message.dequeue` | alt+up, alt+down | composer |\n| `app.clipboard.pasteImage` | ctrl+v (darwin/linux) / alt+v (win32) | composer |\n| `app.clipboard.copyLine` | alt+shift+l | composer |\n| `app.clipboard.copyPrompt` | alt+shift+c | composer |\n| `app.oauth.copyUrl` | alt+shift+u | composer |\n| `app.session.new` | ctrl+n | composer |\n| `app.session.tree` | _(none)_ | composer |\n| `app.session.fork` | _(none)_ | composer |\n| `app.session.resume` | alt+r | composer |\n| `app.session.continue` | ctrl+q | composer |\n| `app.session.observe` | ctrl+s | composer |\n| `app.session.dashboard` | _(none)_ | composer |\n| `app.jobs.open` | alt+j | composer |\n| `app.session.togglePath` | ctrl+p | selector |\n| `app.session.toggleSort` | ctrl+s | selector |\n| `app.session.rename` | ctrl+r | selector |\n| `app.session.delete` | ctrl+d | selector |\n| `app.session.deleteNoninvasive` | ctrl+backspace | selector |\n| `app.tree.foldOrUp` | ctrl+left, alt+left | selector |\n| `app.tree.unfoldOrDown` | ctrl+right, alt+right | selector |\n| `app.plan.toggle` | alt+shift+p | composer |\n| `app.history.search` | ctrl+r | composer |\n| `app.stt.toggle` | alt+h | composer |\n| `app.irc.sidebar.toggle` | alt+i | composer |\n| `app.transcript.browse` | _(none)_ | composer |\n| `app.transcript.prevTurn` | _(none)_ | composer |\n| `app.transcript.nextTurn` | _(none)_ | composer |\n| `app.mode.cycle` | _(none)_ | composer |\n| `app.tasks.toggle` | alt+t | composer |\n| `app.queue.togglePane` | _(none)_ | composer |\n| `app.message.sendNow` | _(none)_ | composer |\n\n### Global engine context (`tui.global.*`)\n\n| Action ID | Default | Notes |\n| --- | --- | --- |\n| `tui.global.debug` | `shift+ctrl+d` | Toggle debug overlay; resolved through the registry in `tui.ts` |\n\nCross-context default reuse (`ctrl+s`, `ctrl+r`, `ctrl+d`, `ctrl+b`, `ctrl+left`/`ctrl+right`, `enter`, `escape`, `ctrl+c`) is intentional: each pair is active in a different focused context and is disambiguated at dispatch time. Use `detectDefaultKeyCollisions()` (above) to re-derive this list from the registry.\n\n### Not yet registry-managed\n\nA few contexts still match chords directly instead of resolving through the registry, and are tracked for a later phase:\n\n- Tree selector (`tree-selector.ts`): up/down/left/right/enter, `ctrl+c`, filter cycling (`ctrl+o` / `ctrl+shift+o`), filter modes (`alt+d/t/u/l/a`), label edit (`shift+l`).\n- Parts of the model selector.\n",
|
|
39
39
|
"lsp-config.md": "# LSP configuration in SKC\n\nThis guide explains how to configure language servers for the SKC coding agent.\n\nSource of truth in code:\n\n- Server config type: `packages/coding-agent/src/lsp/types.ts` (`ServerConfig`)\n- Config loader: `packages/coding-agent/src/lsp/config.ts`\n- Built-in server definitions: `packages/coding-agent/src/lsp/defaults.json`\n\n## Auto-detection\n\nWhen no LSP config file is present, SKC auto-detects servers by intersecting two conditions:\n\n1. The project directory contains at least one of the server's `rootMarkers`.\n2. The server binary is a trusted external executable. Project-local binaries, including paths reached through symlinks, are rejected.\n\nNo configuration is required for common setups. The built-in server list covers most popular languages; see [`defaults.json`](../packages/coding-agent/src/lsp/defaults.json) for the full set.\n\n## Config file locations\n\nSKC merges LSP config from multiple files, lowest to highest priority:\n\n| Priority | Location |\n|----------|----------|\n| 5 (lowest) | `~/lsp.json`, `~/.lsp.json`, `~/lsp.yaml`, `~/.lsp.yaml` |\n| 4 | Preloaded trusted external plugin LSP config outside the project (internal loader support; no current CLI/startup producer) |\n| 3 | `~/.skc/agent/lsp.json`, `~/.skc/agent/lsp.yaml`, `~/.gemini/lsp.*` |\n| 2 | `<project>/.skc/lsp.json`, `<project>/.skc/lsp.yaml`, `<project>/.gemini/lsp.*` |\n| 1 (highest) | `<project>/lsp.json`, `<project>/.lsp.json`, `<project>/lsp.yaml` |\n\nEach location accepts both `.json` and `.yaml` / `.yml` variants, as well as hidden-file versions (`.lsp.json`, `.lsp.yaml`). Configuration is merged in order, but project-controlled files can only control declarative server matching, activation, and capabilities. They cannot define or override a server's `command`, `args`, executable, client factory, `initOptions` / `initializationOptions`, or `settings`; opaque options that can instruct a trusted server belong to trusted user configuration.\n\nThe recommended trusted user configuration is `~/.skc/agent/lsp.json` (or YAML equivalent). Legacy user-wide `~/.gemini/lsp.*` and home-root `~/lsp.*` / `~/.lsp.*` files are also outside the project and may define launch settings and opaque server options, including custom servers. Project files may refine declarative matching and activation fields of built-in or user-defined servers.\n\n**Recommended locations:**\n\n- Trusted user launch settings, `initOptions`, and `settings` → `~/.skc/agent/lsp.json`\n- Project-specific matching and activation → `<project>/.skc/lsp.json`\n\n> **Note:** The presence of any LSP config file disables auto-detection. When at least one file is found, SKC skips the binary-scan phase and loads matching, available, non-disabled servers using trusted launch definitions.\n\n## File shape\n\nBoth JSON and YAML are accepted. The top-level object can use either a `servers` wrapper key or a flat map directly:\n\n```json\n{\n \"servers\": {\n \"server-name\": { ... }\n },\n \"idleTimeoutMs\": 300000\n}\n```\n\nor (flat, without the `servers` wrapper):\n\n```json\n{\n \"server-name\": { ... },\n \"idleTimeoutMs\": 300000\n}\n```\n\nTop-level keys:\n\n- `servers` — map of server name to `ServerConfig` (optional wrapper; flat form is equivalent)\n- `idleTimeoutMs` — shut down idle language servers after this many milliseconds; disabled by default\n\n## ServerConfig fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `command` | `string` | trusted user config only | Server executable name or absolute path; project configuration cannot set or override it |\n| `args` | `string[]` | no | Launch arguments; trusted user config only |\n| `fileTypes` | `string[]` | yes | File extensions this server handles, e.g. `[\".ts\", \".tsx\"]` |\n| `rootMarkers` | `string[]` | yes | Files/dirs that indicate a project root; glob patterns (e.g. `*.cabal`) are supported |\n| `initOptions` | `object` | trusted user config only | Sent as `initializationOptions` during LSP handshake |\n| `settings` | `object` | trusted user config only | Workspace settings pushed via `workspace/didChangeConfiguration` |\n| `disabled` | `boolean` | no | Set to `true` to disable this server entirely |\n| `warmupTimeoutMs` | `number` | no | Startup timeout in ms for this server (overrides the global default) |\n| `isLinter` | `boolean` | no | Mark server as linter/formatter only; excluded from type-intelligence operations (hover, go-to-definition, etc.) |\n| `capabilities` | `object` | no | Opt-in server-specific features; see [Capabilities](#capabilities) |\n\n`resolvedCommand` is populated automatically at runtime — do not set it manually.\n\n### Capabilities\n\nThe `capabilities` object enables optional server-specific features that SKC supports on a per-server basis:\n\n```json\n{\n \"capabilities\": {\n \"flycheck\": true,\n \"ssr\": true,\n \"expandMacro\": true,\n \"runnables\": true,\n \"relatedTests\": true\n }\n}\n```\n\nAll fields are boolean and optional. They are currently used by `rust-analyzer`.\n\n## Common recipes\n\n### Override a built-in server's settings from trusted user configuration\n\nOpaque server settings may contain process-affecting instructions, so place these partial overrides in trusted user configuration such as `~/.skc/agent/lsp.json`:\n\n```json\n{\n \"servers\": {\n \"typescript-language-server\": {\n \"settings\": {\n \"typescript\": {\n \"preferences\": {\n \"quoteStyle\": \"single\"\n }\n }\n }\n }\n }\n}\n```\n\n```yaml\nservers:\n gopls:\n settings:\n gopls:\n gofumpt: false\n staticcheck: false\n```\n\n### Disable a built-in server\n\n```json\n{\n \"servers\": {\n \"eslint\": {\n \"disabled\": true\n }\n }\n}\n```\n\n### Register a custom server\n\nRegister custom servers in the canonical trusted user configuration, `~/.skc/agent/lsp.json`. New servers require `command`, `fileTypes`, and `rootMarkers`; `args` is optional. Project configuration cannot register a launch definition or override a server's command, arguments, executable, or client factory.\n\n```json\n{\n \"servers\": {\n \"my-lsp\": {\n \"command\": \"my-lsp-server\",\n \"args\": [\"--stdio\"],\n \"fileTypes\": [\".xyz\"],\n \"rootMarkers\": [\".xyz-project\", \".git\"]\n }\n }\n}\n```\n\n### Set a global idle timeout\n\nShut down language servers that have been inactive for more than five minutes:\n\n```json\n{\n \"idleTimeoutMs\": 300000\n}\n```\n\n### Disable a server for one project, keep it globally\n\nPlace the override in `<project>/.skc/lsp.json`:\n\n```json\n{\n \"servers\": {\n \"pylsp\": {\n \"disabled\": true\n }\n }\n}\n```\n\nThe user-level config in `~/.skc/agent/lsp.json` is unaffected; pylsp is only suppressed in this project.\n\nWhen multiple built-in primary servers support the same file, a default server can list lower-precedence servers in `supersedes`. For example, `csharp-ls` supersedes `omnisharp` only when both C# servers are installed and detected; if `csharp-ls` is unavailable, `omnisharp` remains the fallback.\n\n## lspmux\n\n`SKC_DISABLE_LSPMUX=1` is the canonical opt-out. `PI_DISABLE_LSPMUX=1` is a supported compatibility alias. A truthy value for either variable disables lspmux probing and wrapping.\n\n## Built-in server list\n\nThe following servers ship in `defaults.json` and are eligible for auto-detection:\n\n| Server key | Language(s) | Binary |\n|---|---|---|\n| `rust-analyzer` | Rust | `rust-analyzer` |\n| `clangd` | C, C++, ObjC | `clangd` |\n| `zls` | Zig | `zls` |\n| `gopls` | Go | `gopls` |\n| `typescript-language-server` | TypeScript, JavaScript | `typescript-language-server` |\n| `denols` | TypeScript, JavaScript (Deno) | `deno` |\n| `biome` | TS/JS/JSON (linter) | `biome` |\n| `eslint` | TS/JS/Vue/Svelte (linter) | `vscode-eslint-language-server` |\n| `vscode-html-language-server` | HTML | `vscode-html-language-server` |\n| `vscode-css-language-server` | CSS, SCSS, Less | `vscode-css-language-server` |\n| `vscode-json-language-server` | JSON | `vscode-json-language-server` |\n| `tailwindcss` | HTML, CSS, TS/JS | `tailwindcss-language-server` |\n| `svelte` | Svelte | `svelteserver` |\n| `vue-language-server` | Vue | `vue-language-server` |\n| `astro` | Astro | `astro-ls` |\n| `pyright` | Python | `pyright-langserver` |\n| `basedpyright` | Python | `basedpyright-langserver` |\n| `pylsp` | Python | `pylsp` |\n| `ruff` | Python (linter) | `ruff` |\n| `jdtls` | Java | `jdtls` |\n| `kotlin-lsp` | Kotlin | `kotlin-lsp` |\n| `metals` | Scala | `metals` |\n| `hls` | Haskell | `haskell-language-server-wrapper` |\n| `ocamllsp` | OCaml | `ocamllsp` |\n| `elixirls` | Elixir | `elixir-ls` |\n| `erlangls` | Erlang | `erlang_ls` |\n| `gleam` | Gleam | `gleam` |\n| `solargraph` | Ruby | `solargraph` |\n| `ruby-lsp` | Ruby | `ruby-lsp` |\n| `rubocop` | Ruby (linter) | `rubocop` |\n| `bashls` | Bash, Zsh | `bash-language-server` |\n| `lua-language-server` | Lua | `lua-language-server` |\n| `intelephense` | PHP | `intelephense` |\n| `phpactor` | PHP | `phpactor` |\n| `csharp-ls` | C# | `csharp-ls` |\n| `omnisharp` | C# | `omnisharp` |\n| `yamlls` | YAML | `yaml-language-server` |\n| `terraformls` | Terraform | `terraform-ls` |\n| `dockerls` | Dockerfile | `docker-langserver` |\n| `helm-ls` | Helm | `helm_ls` |\n| `nixd` | Nix | `nixd` |\n| `nil` | Nix | `nil` |\n| `ols` | Odin | `ols` |\n| `dartls` | Dart | `dart` |\n| `marksman` | Markdown | `marksman` |\n| `texlab` | LaTeX | `texlab` |\n| `graphql` | GraphQL | `graphql-lsp` |\n| `prismals` | Prisma | `prisma-language-server` |\n| `vimls` | Vim script | `vim-language-server` |\n| `emmet-language-server` | HTML, CSS, JSX | `emmet-language-server` |\n| `sourcekit-lsp` | Swift | `sourcekit-lsp` |\n| `swiftlint` | Swift (linter) | `swiftlint` |\n| `tlaplus` | TLA+ | `tlapm_lsp` |\n",
|
|
40
40
|
"memory.md": "# Autonomous Memory\n\nWhen enabled, the agent automatically extracts durable knowledge from past sessions and injects a compact summary into each new session. Over time it builds a project-scoped memory store — technical decisions, recurring workflows, pitfalls — that carries forward without manual effort.\n\nDisabled by default. Enable via `/settings` or `config.yml`:\n\n```yaml\nmemories:\n enabled: true\n```\n\n## Usage\n\n### What gets injected\n\nAt session start, if a memory summary exists for the current project, it is injected into the system prompt as a **Memory Guidance** block. The agent is instructed to:\n\n- Treat memory as heuristic context — useful for process and prior decisions, not authoritative on current repo state.\n- Pair memory-influenced decisions with current-repo evidence before acting.\n- Prefer repo state and user instruction when they conflict with memory; treat conflicting memory as stale.\n\n### Memory artifacts\n\nGenerated local-memory artifacts are private runtime state, not a public tool or URI surface. They may be summarized into the system prompt when local memory is enabled, but users and model-facing tool docs should not rely on direct `memory://` reads. The legacy internal `memory://` resolver remains only for compatibility with existing persisted guidance and is not part of the public coding harness contract; remove it after legacy local-memory prompts no longer reference it.\n### `/memory` slash command\n\n| Subcommand | Effect |\n| --------------------- | ---------------------------------------------- |\n| `view` | Show the current memory injection payload |\n| `clear` / `reset` | Delete all memory data and generated artifacts |\n| `enqueue` / `rebuild` | Force consolidation to run at next startup |\n\n## How it works\n\nMemories are built by a background pipeline that runs at startup or when manually triggered via slash command.\n\n**Phase 1 — per-session extraction:** For each past session that has changed since it was last processed, a model reads the session history and extracts durable signal: technical decisions, constraints, resolved failures, recurring workflows. Sessions that are too recent, too old, or currently active are skipped. Each extraction produces a raw memory block and a short synopsis for that session.\n\n**Phase 2 — consolidation:** After extraction, a second model pass reads all per-session extractions and produces three outputs written to disk:\n\n- `MEMORY.md` — a curated long-term memory document\n- `memory_summary.md` — the compact text injected at session start\n- `skills/` — reusable procedural playbooks, each in its own subdirectory\n\nPhase 2 uses a lease to prevent double-running when multiple processes start simultaneously. Stale skill directories from prior runs are pruned automatically.\n\nAll output is scanned for secrets before being written to disk.\n\n### Extraction behavior\n\nMemory extraction and consolidation behavior is driven by static prompt files in `packages/coding-agent/src/prompts/memories/`.\n\n| File | Purpose | Variables |\n| --------------------- | ------------------------------------------- | ------------------------------------------- |\n| `stage_one_system.md` | System prompt for per-session extraction | — |\n| `stage_one_input.md` | User-turn template wrapping session content | `{{thread_id}}`, `{{response_items_json}}` |\n| `consolidation.md` | Prompt for cross-session consolidation | `{{raw_memories}}`, `{{rollout_summaries}}` |\n| `read_path.md` | Memory guidance injected into live sessions | `{{memory_summary}}` |\n\n### Model selection\n\nMemory piggybacks on the model role system.\n\n| Phase | Role | Purpose |\n| ----------------------- | ------------------------------------------------------------------- | -------------------------------- |\n| Phase 1 (extraction) | `default` | Per-session knowledge extraction |\n| Phase 2 (consolidation) | `smol` (falls back to `default`, then current/first registry model) | Cross-session synthesis |\n\nIf the requested memory role is not configured, memory model resolution falls back to the `default` role, then the active session model, then the first model in the registry.\n\n## Configuration\n\n| Setting | Default | Description |\n| ------------------------------------- | ------- | --------------------------------------------------------- |\n| `memories.enabled` | `false` | Master switch |\n| `memories.maxRolloutAgeDays` | `30` | Sessions older than this are not processed |\n| `memories.minRolloutIdleHours` | `12` | Sessions active more recently than this are skipped |\n| `memories.maxRolloutsPerStartup` | `64` | Cap on sessions processed in a single startup |\n| `memories.summaryInjectionTokenLimit` | `5000` | Max tokens of the summary injected into the system prompt |\n\nAdditional tuning knobs (concurrency, lease durations, token budgets) are available in config for advanced use.\n\n## Key files\n\n- `packages/coding-agent/src/memories/index.ts` — pipeline orchestration, injection, slash command handling\n- `packages/coding-agent/src/memories/storage.ts` — SQLite-backed job queue and thread registry\n- `packages/coding-agent/src/prompts/memories/` — memory prompt templates\n- `packages/coding-agent/src/internal-urls/memory-protocol.ts` — legacy non-public `memory://` compatibility handler\n",
|
|
41
|
+
"messenger-initiated-sessions.md": "# Messenger-Initiated Sessions — Future Work\n\nStatus: **backlog / not started** · Recorded 2026-10-19 · No code exists for this yet.\n\nGoal: let the operator start and drive real coding work from a phone messenger\n(Discord, Slack, Telegram) while the PC is on, without first opening an `skc`\nsession at the PC. The PC still does all the work; the phone is only where\ninstructions go in and results come out.\n\n## What exists today\n\nSKC already attaches a **running** PC-side session to a messenger. It cannot\ncreate a session from the messenger side.\n\n| Capability | Where |\n|---|---|\n| Discord / Slack / Telegram adapters | `packages/coding-agent/src/sdk/bus/discord-*`, `slack-*`, `telegram-*`; `packages/telegram-remote` |\n| One running session ↔ one Discord thread | `sdk/bus/discord-conversation.ts` (`discordConversationKey`, `acceptsDiscordInbound`) |\n| Write-ahead delivery journal with an `uncertain` state | `sdk/bus/chat-effect-journal.ts` (`pending` → `leased` → `accepted` / `uncertain` / `terminal`) |\n| Long-running chat daemon | `sdk/bus/chat-daemon-runtime.ts`, `skc daemon` |\n| Session broker | `packages/coding-agent/src/sdk/broker` |\n| Setup | `skc notify setup discord|slack|telegram` ([discord](discord-onboarding.md), [slack](slack-onboarding.md), [telegram](telegram-onboarding.md)) |\n| Phone steering wheel design (read + one-line submit to existing sessions) | [`sayknow-remote.md`](sayknow-remote.md) |\n\nThe current authority rule from [`sayknow-remote.md`](sayknow-remote.md) is that\nthe PC remains the authority for file edits, shell execution, and approval\ngates; the phone observes and submits to sessions the PC already started.\n\n## The gap\n\n| | Today (SKC) | This proposal |\n|---|---|---|\n| Session the messenger talks to | A session already running in a PC terminal | A session the daemon creates for that conversation |\n| Start new work from the phone | No | Yes, by sending a DM |\n| PC requirement | `skc` session open | Daemon running, PC on and online |\n\nThis is a change to the authority rule above: a messenger message would be able\nto cause shell execution on the PC without anyone at the PC. It needs an\nexplicit design decision (ADR) before implementation.\n\n## Proposed shape\n\n1. **Conversation-keyed sessions.** The daemon maps each accepted conversation\n (`platform/kind/conversationId`) to one SKC session and an epoch. `/new`\n increments that conversation's epoch and binds the next message to a fresh\n session, leaving other conversations untouched. Session creation must be\n idempotent on (daemon instance, conversation key, epoch) so a crash during\n creation retries instead of duplicating.\n2. **Per-conversation mailbox.** If a turn is running, an inbound message is\n steered into it; if idle, it starts the next turn. Messages are durable until\n a turn takes them.\n3. **Dedicated workspace.** Messenger-created sessions run in a configured\n workspace directory, not in whatever directory the PC user last used.\n4. **Reuse the existing delivery journal.** Replies go through\n `chat-effect-journal.ts`; an uncertain send is re-sent and visibly labelled\n as a possible duplicate rather than silently dropped.\n\n## Safety requirements (must ship with the feature, not after)\n\n1. **Owner-only by default.** DMs from anyone other than configured owner IDs\n are ignored. Group channels require a real mention and are closed unless\n explicitly opened.\n2. **Approval gates for destructive actions.** commit, push, deploy, delete,\n and restart require an explicit approval reply from an owner in the\n messenger; no silent auto-approval.\n3. **Mandatory outbound secret redaction.** Every outbound chat message and\n progress label passes a secret filter that configuration cannot disable:\n known credential formats (`sk-ant-`, `sk-`, `ghp_`/`github_pat_`, `AKIA`,\n `xox*`, JWTs, PEM keys, `Bearer` tokens) and exact values of secret-named\n environment variables become `[REDACTED:<kind>]`.\n - Today's `notifications.redact` (`sdk/bus/config.ts`, `buildRedactedAction`)\n is different: it is opt-in (default `false`) and drops summaries/streams\n wholesale rather than filtering secrets out of messages that are sent.\n - This item is independent of the rest of the proposal and is the\n lowest-risk piece to implement first, for existing notifications too.\n4. **Bot-loop limits.** A rolling per-conversation rate limit on bot-authored\n turns so two agents in one channel cannot loop indefinitely.\n5. **Account compromise model.** Document that a compromised messenger account\n equals remote command execution within the gates above.\n\n## Optional follow-ups\n\n- Scheduled / event monitors that give the agent its own turns (for example a\n daily self-check), delivered to a configured conversation.\n- Human-readable Markdown memory per conversation under the daemon home.\n\nThese only make sense once messenger-initiated sessions exist.\n\n## Suggested order\n\n1. Mandatory outbound secret redaction (safety item 3) for existing\n notification surfaces.\n2. ADR: change the PC-authority rule for messenger-initiated sessions, with the\n safety requirements above as acceptance criteria.\n3. Conversation-keyed session creation + `/new` epochs + owner-only gate.\n4. Approval gates over the messenger.\n5. Optional monitors and memory.\n\n## Reference and licensing\n\nThe idea comes from reviewing\n[`Yeachan-Heo/gajae-way`](https://github.com/Yeachan-Heo/gajae-way), a gateway\nthat hosts `gjc` agent sessions behind Discord/Slack/Telegram. It is licensed\n**AGPL-3.0**; SKC packages are MIT. Use it as a design reference only — do not\ncopy its code into this repository.\n\n## Non-goals\n\n- Editing code on the phone or rendering full diffs there.\n- A remote shell or remote desktop.\n- Running work while the PC is off (no cloud execution).\n",
|
|
41
42
|
"models.md": "# Model and Provider Configuration (`models.yml`)\n\nThis document describes how the coding-agent currently loads models, applies overrides, resolves credentials, and chooses models at runtime.\n\n## What controls model behavior\n\nPrimary implementation files:\n\n- `src/config/model-registry.ts` — loads built-in + custom models, provider overrides, runtime discovery, auth integration\n- `src/config/model-resolver.ts` — parses model patterns and selects models for the default and agent roles\n- `src/config/settings-schema.ts` — model-related settings (`modelRoles`, provider transport preferences)\n- `src/session/auth-storage.ts` — API key + OAuth resolution order\n- `packages/ai/src/models.ts` and `packages/ai/src/types.ts` — built-in providers/models and `Model`/`compat` types\n\n## Config file location and legacy behavior\n\nDefault config path:\n\n- `~/.skc/agent/models.yml`\n\nLegacy behavior still present:\n\n- If `models.yml` is missing and `models.json` exists at the same location, it is migrated to `models.yml`.\n- Explicit `.json` / `.jsonc` config paths are still supported when passed programmatically to `ModelRegistry`.\n\n## `models.yml` shape\n\n```yaml\nproviders:\n <provider-id>:\n # provider-level config\nequivalence:\n overrides:\n <provider-id>/<model-id>: <canonical-model-id>\n exclude:\n - <provider-id>/<model-id>\n```\n\n`provider-id` is the canonical provider key used across selection and auth lookup.\n\n`equivalence` is optional and configures canonical model grouping on top of concrete provider models:\n\n- `overrides` maps an exact concrete selector (`provider/modelId`) to an official upstream canonical id\n- `exclude` opts a concrete selector out of canonical grouping\n\n## Provider-level fields\n\n```yaml\nproviders:\n my-provider:\n baseUrl: https://api.example.com/v1\n apiKey: MY_PROVIDER_API_KEY\n api: openai-completions\n headers:\n X-Team: platform\n authHeader: true\n auth: apiKey\n disableStrictTools: false # set true for Anthropic-compatible endpoints that reject the strict field\n cacheRetention: short # none | short | long; model entries and modelOverrides can override this\n discovery:\n type: ollama\n modelOverrides:\n some-model-id:\n name: Renamed model\n cacheRetention: long\n models:\n - id: some-model-id\n name: Some Model\n api: openai-completions\n reasoning: false\n input: [text]\n cost:\n input: 0\n output: 0\n cacheRead: 0\n cacheWrite: 0\n contextWindow: 128000\n maxTokens: 16384\n headers:\n X-Model: value\n cacheRetention: none\n thinking:\n minLevel: low\n maxLevel: xhigh\n mode: effort\n defaultLevel: high\n levels: [low, medium, high, xhigh]\n compat:\n supportsStore: true\n supportsDeveloperRole: true\n supportsReasoningEffort: true\n maxTokensField: max_completion_tokens\n openRouterRouting:\n only: [anthropic]\n vercelGatewayRouting:\n order: [anthropic, openai]\n extraBody:\n gateway: m1-01\n controller: mlx\nmodelBindings:\n modelRoles:\n default: my-provider/some-model-id:high\n agentModelOverrides:\n executor: my-provider/some-model-id\n```\n\n### Allowed provider/model `api` values\n\n- `openai-completions`\n- `openai-responses`\n- `openai-codex-responses`\n- `azure-openai-responses`\n- `bedrock-converse-stream`\n- `anthropic-messages`\n- `bedrock-converse-stream`\n- `google-generative-ai`\n- `google-vertex`\n- `google-gemini-cli`\n- `ollama-chat`\n- `cursor-agent`\n\n\n### First-class Azure OpenAI and Amazon Bedrock examples\n\nAzure OpenAI uses canonical OpenAI model IDs in SKC and resolves those IDs to Azure deployment names at request time. Set `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` to avoid assuming model id equals deployment name:\n\n```yaml\nproviders:\n azure-openai:\n baseUrl: https://my-resource.openai.azure.com/openai/v1\n apiKeyEnv: AZURE_OPENAI_API_KEY\n api: azure-openai-responses\n models:\n - id: gpt-4.1\n - id: o3\n```\n\n```sh\nexport AZURE_OPENAI_DEPLOYMENT_NAME_MAP='gpt-4.1=gpt-41-prod,o3=o3-reasoning-prod'\n```\n\nAmazon Bedrock uses the native `bedrock-converse-stream` transport and AWS credential chain auth. Do not put AWS access keys in `models.yml`; configure `AWS_REGION` / `AWS_PROFILE` or standard static AWS credential environment variables instead:\n\n```yaml\nproviders:\n amazon-bedrock:\n baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com\n api: bedrock-converse-stream\n models:\n - id: us.anthropic.claude-opus-4-6-v1\n - id: anthropic.claude-3-5-sonnet-20241022-v2:0\n```\n\n### MiniMax and GLM custom provider examples\n\nFor common MiniMax and GLM/zAI setup, prefer the provider presets so the OpenAI-compatible API, base URL, env var, model id, and compatibility flags are written together:\n\n```sh\nskc setup provider --preset minimax\nskc setup provider --preset minimax-cn\nskc setup provider --preset glm\nskc setup provider --preset alibaba-token-plan\n```\n\nThe same presets are available inside the TUI:\n\n```text\n/provider add --preset minimax\n/provider add --preset glm\n/provider add zai\n/provider add --preset alibaba-token-plan\n```\n\nPresets only write `models.yml` entries that reference documented environment variable names (`MINIMAX_CODE_API_KEY`, `MINIMAX_CODE_CN_API_KEY`, `ZAI_API_KEY`, or `ALIBABA_TOKEN_PLAN_API_KEY`); they do not store or validate real credentials. The GLM preset aliases (`glm`, `zai`, `z-ai`) write an OpenAI-compatible custom provider named `glm-proxy` and do not replace the first-class `zai` provider. The Alibaba Token Plan preset (aliases: alibaba, token-plan) writes an OpenAI-compatible custom provider named alibaba-token-plan with per-model API routing (qwen3.8-max-preview uses openai-responses; glm-5.2 and deepseek-v4-pro use openai-completions).\n\n## Model profiles (`--mpreset`)\n\nModel profiles are optional top-level `profiles:` entries in `~/.skc/agent/models.yml`. A profile can require provider credentials before activation and can map one or more model roles; omitted roles inherit from the active defaults.\n\n> See also: [Cross-vendor role-based profiles](./multi-vendor-profiles.md) — a curated multi-vendor `profiles:` recipe and verified selector notes that build on the mechanism described here.\n\n```yaml\nprofiles:\n team-standard:\n required_providers: [openai, anthropic]\n model_mapping:\n default: openai/gpt-5.2\n executor: anthropic/claude-sonnet-4-6:medium\n architect: openai/o3:high\n planner: openai/o3:high\n critic: openai/o3:high\n```\n\n`model_mapping` keys are role names (`default`, `executor`, `architect`, `planner`, `critic`). Each role maps to exactly one model selector in the form `provider/modelId[:effort]`; comma-separated fallback chains are not supported in a single role value.\n`required_providers` is the aggregate set of providers required across the profile's mapped roles, not a per-role fallback chain.\n\nBuilt-in profiles are grouped by provider mix and tier:\n\n- `codex-{eco,medium,pro}` — all roles on `openai-codex/gpt-5.5`, differing only by per-role reasoning effort\n- `opencodego` — single OpenCode Go preset (Kimi default, DeepSeek executor/architect, Qwen planner, MiMo critic)\n- `claude-opus` — Anthropic OAuth preset centered on `claude-opus-5`\n- `claude-opus-5-5` — Anthropic preset centered on `claude-opus-5-5` (`xhigh` default, `max` architect, `high` critic, `medium` planner, `claude-sonnet-5` executor). Recommended automatically after an Anthropic login; `claude-opus` stays available for the Opus 5 cost/effort shape.\n- Single-provider tiers: `glm-{eco,medium,pro}`, `kimi-coding-plan-{eco,medium,pro}`, `mimo-{eco,medium,pro}`, `grok-{eco,medium,pro}`, `cursor-{eco,medium,pro}`, `minimax-{eco,medium,pro}`\n- Combos: `opus-codex` (Claude main agent with Codex support roles), `codex-opencodego` (Codex orchestrator/architect with OpenCode Go workers)\n\nThe `eco`, `medium`, and `pro` Codex profile mappings are current product judgments: Eco assigns Terra low/Luna low/Luna high/Terra xhigh/Terra high to default/executor/planner/critic/architect; Medium assigns Sol low/Terra low/Terra high/Sol xhigh/Sol high; and Pro assigns Sol medium/Terra medium/Sol high/Sol max/Sol xhigh. `opus-codex` retains the Medium Codex executor, critic, and architect roles but uses `anthropic/claude-sonnet-5` for planner; `codex-opencodego` retains the Medium Codex default and architect roles; and `fable-opus-codex` uses the Pro Codex executor and architect roles with `anthropic/claude-opus-5:medium` for planner. The descriptive repeated local exact-edit evidence informs only selected executor-style TypeScript tasks; it does not evaluate or prove default, planner, architect, or critic performance. See [GPT-5.6 Codex preset benchmark](./gpt-5.6-codex-preset-benchmark.md). Effort suffixes are clamped to each model's supported thinking range at preview and activation time. Single-provider tiers pin each provider's current flagship (`zai/glm-5.2`, `kimi-code/kimi-k2.7-code`, `xiaomi/mimo-v2.5-pro`, `xai/grok-4.3`, `cursor/composer-1.5`, `minimax-code/minimax-m3`). User-defined profiles override built-ins by exact profile name.\n\n\nUse `skc --mpreset <name>` to activate a profile for the current session only. Activation hard-blocks when any provider listed in `required_providers` lacks credentials. Add `--default` to persist the selected profile as `modelProfile.default` in `config.yml`, so it applies at startup:\n\n```sh\nskc --mpreset codex-medium\nskc --mpreset opencodego --default\n```\n\nThe `/model` command opens to a preset landing view: presets are grouped by provider with live auth marks (✓/✗), highlighting a group expands its tiers, and selecting a tier shows the full role→model preview before applying for the session or as default. Typing jumps straight to model search, and `Browse all models` opens the classic tabbed model selector. In `/login`, `Add custom provider` is the first option for configuring credentials needed by custom or profile-required providers; after a successful provider login, the matching preset is recommended automatically.\n\nMiniMax's OpenAI-compatible endpoint rejects multiple system messages and emits thinking in `reasoning_content`, so pin the public-safe compatibility fields when hand-authoring a custom provider:\n\n```yaml\nproviders:\n minimax-custom:\n baseUrl: https://api.minimax.io/v1\n apiKeyEnv: MINIMAX_API_KEY\n api: openai-completions\n compat:\n supportsStore: false\n supportsDeveloperRole: false\n supportsReasoningEffort: false\n reasoningContentField: reasoning_content\n models:\n - id: MiniMax-M2.5\n```\n\nGLM via z.ai is available as the first-class `zai` provider. For a private GLM-compatible proxy, keep secrets in an env var and disable OpenAI-only request fields as needed:\n\n```yaml\nproviders:\n glm-proxy:\n baseUrl: https://api.z.ai/api/paas/v4\n apiKeyEnv: ZAI_API_KEY\n api: openai-completions\n compat:\n supportsDeveloperRole: false\n supportsReasoningEffort: false\n models:\n - id: glm-4.6\n```\n### Allowed auth/discovery values\n\n- `auth`: `apiKey` (default), `none`, or `oauth`; for `models.yml` custom models, `oauth` is accepted by schema but does not waive the `apiKey` requirement\n- `models.yml` is strict: unknown provider/model keys fail validation before provider dispatch, so stale keys such as `requestTransform` or `wireModelId` only work where this document lists them.\n- `discovery.type`: `ollama`, `llama.cpp`, `lm-studio`, `omlx`, `sglang`, or `openai-models-list`\n- `cacheRetention`: `none`, `short`, or `long`; request-time options win over model/modelOverride values, then provider values, then `SKC_CACHE_RETENTION`, then the runtime default. The runtime default is `short` for most providers, but the Anthropic provider defaults to `long` (`ttl: \"1h\"`) because the ~5m default is too fragile for long-running subagent workflows. The 1h marker is only emitted on the canonical Anthropic API (`api.anthropic.com`) for models advertising `supportsLongCacheRetention`; proxies, gateways, and incapable models fall back to the default ephemeral (~5m) breakpoint. For OpenAI Responses, this controls `prompt_cache_retention` only; it does not disable `prompt_cache_key` when a stable session id exists.\n\n## OpenAI-compatible proxy configuration\n\nOpenAI-compatible proxy providers should use schema-supported provider keys first:\n\n```yaml\nproviders:\n proxy-provider:\n baseUrl: https://api.proxy.example/v1\n apiKeyEnv: PROXY_API_KEY\n api: openai-completions\n auth: apiKey\n headers:\n User-Agent: curl/8.7.1\n models:\n - id: local-gpt\n name: Local GPT\n reasoning: true\n input: [text]\n cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n contextWindow: 400000\n maxTokens: 128000\n```\n\nUse provider-level `headers` for proxy-required headers. Keep the provider `api` set to `openai-completions` when the proxy exposes Chat Completions-compatible `/v1/chat/completions` semantics. `auth: apiKey` sends the resolved token as bearer auth; use `auth: none` only for trusted local/no-auth endpoints.\n\n`input` is the model modality list SKC uses to decide whether image content is forwarded. When a custom model omits `input`, SKC defaults to `[text]` (unless a bundled model with the same id contributes a reference). Vision-capable upstream models therefore need an explicit `input: [text, image]`; otherwise `read`/tool images are stripped before the request and replaced with `[image omitted: model does not support vision]`, even if the remote model can see images.\n\n```yaml\nproviders:\n ali:\n baseUrl: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n apiKeyEnv: ALI_API_KEY\n api: openai-completions\n auth: apiKey\n models:\n # id-only → text-only; images will be omitted\n - id: some-text-model\n # vision-capable hosted model must declare image input\n - id: qwen3.8-max-preview\n name: Qwen3.8 Max Preview\n reasoning: true\n input: [text, image]\n```\n\n`requestTransform` and `wireModelId` remain supported for request-body shaping, but they are not needed for ordinary OpenAI-compatible proxies whose local model id is already the upstream wire id. Unknown config keys fail validation before a provider request is sent.\n\nWhen request shaping is needed:\n\n- `requestTransform.profile: openai-proxy` strips OpenAI SDK/Stainless telemetry and beta headers at final fetch time and sets a generic SKC user agent.\n- `stripHeaders` replaces the preset strip list when provided.\n- `setHeaders` is applied after stripping; use `null` to remove a header.\n- `extraBody` is shallow-merged into the JSON request body after provider compatibility fields; core transport keys such as `model`, `messages`/`input`, `stream`, `tools`, and `tool_choice` are protected and ignored.\n- Model-level `requestTransform` overrides provider-level fields and shallow-merges `setHeaders`/`extraBody`.\n- `wireModelId` changes only the upstream request body model id; local selection still uses `provider/id`.\n\n### Layofflabs-style proxy example\n\n```yaml\nproviders:\n layofflabs:\n baseUrl: https://api.layofflabs.com/v1\n apiKeyEnv: OPENAI_API_KEY\n api: openai-completions\n auth: apiKey\n headers:\n User-Agent: curl/8.7.1\n models:\n - id: gpt-5.5\n name: GPT 5.5 via Layofflabs\n reasoning: true\n thinking:\n minLevel: low\n maxLevel: xhigh\n mode: effort\n defaultLevel: high\n levels: [low, medium, high, xhigh]\n input: [text]\n cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }\n contextWindow: 400000\n maxTokens: 128000\n\nmodelBindings:\n modelRoles:\n default: layofflabs/gpt-5.5:high\n agentModelOverrides:\n executor: layofflabs/gpt-5.5:high\n```\n\n## Validation rules (current)\n\n### Full custom provider (`models` is non-empty)\n\nRequired:\n\n- `baseUrl`\n- `apiKey` unless `auth: none`\n- `api` at provider level or each model\n\n### Override-only provider (`models` missing or empty)\n\nMust define at least one of:\n\n- `baseUrl`\n- `headers`\n- `compat`\n- `requestTransform`\n- `disableStrictTools`\n- `modelOverrides`\n- `discovery`\n\n### Discovery\n\n- `discovery` requires provider-level `api`.\n\n### Model value checks\n\n- `id` required\n- `contextWindow` and `maxTokens` must be positive if provided\n- unknown provider, model, override, and request-transform keys fail schema validation; remove stale keys instead of relying on them being ignored.\n\n## Merge and override order\n\nModelRegistry pipeline (on refresh):\n\n1. Load built-in providers/models from `@sayknow-cli/ai`.\n2. Load `models.yml` custom config.\n3. Apply provider overrides (`baseUrl`, `headers`, `requestTransform`, `disableStrictTools`, `cacheRetention`) to built-in models.\n4. Apply `modelOverrides` (per provider + model id).\n5. Merge custom `models`:\n - same `provider + id` replaces existing\n - otherwise append\n6. Load cached/runtime-discovered models (Ollama, llama.cpp, LM Studio, plus built-in provider managers), then re-apply model overrides.\n\n### Provider-model cache and static fingerprint\n\nCached per-provider model lists are persisted in the model-cache SQLite\ndatabase (schema v3) with a `static_fingerprint` column that hashes the\nstatic catalog slice merged into the row. When `resolveProviderModels`\nskips the network fetch and the fingerprint of the in-memory static\ncatalog matches the cached one, the cached rows are returned verbatim —\nthe static + dynamic merge is bypassed entirely. The fingerprint is\nmemoized per process via a WeakMap keyed by the static-models array\nreference, so repeated cold-start calls do not re-hash.\n\n## Canonical model equivalence and coalescing\n\nThe registry keeps every concrete provider model and then builds a canonical layer above them.\n\nCanonical ids are official upstream ids only, for example:\n\n- `anthropic-model-opus-4-6`\n- `anthropic-model-haiku-4-5`\n- `gpt-5.3-openai-code`\n\n### `models.yml` equivalence config\n\nExample:\n\n```yaml\nproviders:\n zenmux:\n baseUrl: https://api.zenmux.example/v1\n apiKey: ZENMUX_API_KEY\n api: openai-codex-responses\n models:\n - id: openai-code\n name: Zenmux OpenAI code\n reasoning: true\n input: [text]\n cost:\n input: 0\n output: 0\n cacheRead: 0\n cacheWrite: 0\n contextWindow: 200000\n maxTokens: 32768\n\nequivalence:\n overrides:\n zenmux/openai-code: gpt-5.3-openai-code\n p-openai-code/openai-code: gpt-5.3-openai-code\n exclude:\n - demo/openai-code-preview\n```\n\nBuild order for canonical grouping:\n\n1. exact user override from `equivalence.overrides`\n2. bundled official-id matches from built-in model metadata\n3. conservative heuristic normalization for gateway/provider variants\n4. fallback to the concrete model's own id\n\nCurrent heuristics are intentionally narrow:\n\n- embedded upstream prefixes can be stripped when present, for example `anthropic/...` or `openai/...`\n- dotted and dashed version variants can normalize only when they map to an existing official id, for example `4.6 -> 4-6`\n- ambiguous families or versions are not merged without a bundled match or explicit override\n\n### Canonical resolution behavior\n\nWhen multiple concrete variants share a canonical id, resolution uses:\n\n1. availability and auth\n2. `config.yml` `modelProviderOrder`\n3. existing registry/provider order if `modelProviderOrder` is unset\n\nDisabled or unauthenticated providers are skipped.\n\nSession state and transcripts continue to record the concrete provider/model that actually executed the turn.\n\nProvider defaults vs per-model overrides:\n\n- Provider `headers` are baseline.\n- Model `headers` override provider header keys.\n- `modelOverrides` can override model metadata (`name`, `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`, `headers`, `compat`, `contextPromotionTarget`).\n- `compat` is deep-merged for nested routing blocks (`openRouterRouting`, `vercelGatewayRouting`, `extraBody`).\n\n## Runtime discovery integration\n\n### Implicit Ollama discovery\n\nIf `ollama` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `ollama`\n- api: `openai-responses`\n- base URL: `OLLAMA_BASE_URL` or `http://127.0.0.1:11434`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls Ollama endpoints and normalizes discovered OpenAI-compatible models to `openai-responses`.\n\n### Implicit llama.cpp discovery\n\nIf `llama.cpp` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `llama.cpp`\n- api: `openai-responses`\n- base URL: `LLAMA_CPP_BASE_URL` or `http://127.0.0.1:8080`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery calls llama.cpp model endpoints and synthesizes model entries with local defaults.\n\n### Implicit LM Studio discovery\n\nIf `lm-studio` is not explicitly configured, registry adds an implicit discoverable provider:\n\n- provider: `lm-studio`\n- api: `openai-completions`\n- base URL: `LM_STUDIO_BASE_URL` or `http://127.0.0.1:1234/v1`\n- auth mode: keyless (`auth: none` behavior)\n\nRuntime discovery fetches models (`GET /models`) and synthesizes model entries with local defaults.\n\n### Implicit oMLX discovery\n\nIf `omlx` is not explicitly configured, registry adds an implicit OpenAI-compatible provider at `OMLX_BASE_URL` or `http://127.0.0.1:8080/v1`. Implicit discovery accepts only canonical HTTP(S) loopback URLs without userinfo, query, or fragment; redirects are refused. It discovers models through `GET /v1/models`, accepts `OMLX_API_KEY` when the loopback server requires one, and otherwise uses keyless local auth. Built-in macOS oMLX profiles select the reviewed served model ids and preserve role-specific thinking effort.\n\n### Implicit SGLang discovery\n\nIf `sglang` is not explicitly configured, its bundled OpenAI-compatible descriptor discovers models at trusted `SGLANG_BASE_URL` or `http://127.0.0.1:30000/v1`. Credentialless implicit discovery accepts only HTTP(S) loopback origins, including normalized IPv4, IPv6, and IPv4-mapped loopback forms. Remote SGLang servers require an explicit provider configuration or a trusted base URL plus `SGLANG_API_KEY`; all endpoint URLs must omit userinfo, query, and fragment components, and project-local environment files cannot silently redirect implicit authenticated discovery.\n\n### Explicit provider discovery\n\nYou can configure discovery yourself:\n\n```yaml\nproviders:\n ollama:\n baseUrl: http://127.0.0.1:11434\n api: openai-responses\n auth: none\n discovery:\n type: ollama\n\n llama.cpp:\n baseUrl: http://127.0.0.1:8080\n api: openai-responses\n auth: none\n discovery:\n type: llama.cpp\n```\n\n### Extension provider registration\n\nExtensions can register providers at runtime (`pi.registerProvider(...)`), including:\n\n- model replacement/append for a provider\n- custom stream handler registration for new API IDs\n- custom OAuth provider registration\n\n## Auth and API key resolution order\n\nWhen requesting a key for a provider, effective order is:\n\n1. Runtime override (CLI `--api-key`)\n2. Stored API key credential in `agent.db`\n3. Stored OAuth credential in `agent.db` (with refresh)\n4. Environment variable mapping (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.)\n5. ModelRegistry fallback resolver (provider `apiKey` from `models.yml`, env-name-or-literal semantics)\n\n`models.yml` `apiKey` behavior:\n\n- Value is first treated as an environment variable name.\n- If no env var exists, the literal string is used as the token.\n\nIf `authHeader: true` and provider `apiKey` is set, models get:\n\n- `Authorization: Bearer <resolved-key>` header injected.\n\nKeyless providers:\n\n- Providers marked `auth: none` are treated as available without credentials.\n- `getApiKey*` returns `kNoAuth` for them.\n\n### Broker mode\n\nWhen `SKC_AUTH_BROKER_URL` (or `auth.broker.url`) is set, the local SQLite credential store is replaced by `RemoteAuthCredentialStore`. Layers 2 and 3 above (stored API key / OAuth in `agent.db`) are served from a broker-supplied snapshot whose `refresh` tokens are redacted; expiry triggers `POST /v1/credential/:id/refresh` on the broker rather than a local refresh.\n\n`AuthStorage.setConfigApiKey` lets a `models.yml` `apiKey` win over a broker-resolved OAuth token without overriding a runtime `--api-key`. See [`auth-broker-gateway.md`](./auth-broker-gateway.md) for the full broker / gateway design and env surface (`SKC_AUTH_BROKER_URL`, `SKC_AUTH_BROKER_TOKEN`, `auth.broker.url`, `auth.broker.token`).\n\n## Model availability vs all models\n\n- `getAll()` returns the loaded model registry (built-in + merged custom + discovered).\n- `getAvailable()` filters to models that are keyless or have resolvable auth.\n\nSo a model can exist in registry but not be selectable until auth is available.\n\n## Runtime model resolution\n\n### CLI and pattern parsing\n\n`model-resolver.ts` supports:\n\n- exact `provider/modelId`\n- exact canonical model id\n- exact model id (provider inferred)\n- fuzzy/substring matching\n- glob scope patterns in `--models` (e.g. `openai/*`, `*sonnet*`)\n- optional `:thinkingLevel` suffix (`off|minimal|low|medium|high|xhigh`)\n\n`--provider` is legacy; `--model` is preferred.\n\nResolution precedence for exact selectors:\n\n1. exact `provider/modelId` bypasses coalescing\n2. exact canonical id resolves through the canonical index\n3. exact bare concrete id still works\n4. fuzzy and glob matching run after the exact paths\n\n### Initial model selection priority\n\n`findInitialModel(...)` uses this order:\n\n1. explicit CLI provider+model\n2. first scoped model (if not resuming)\n3. saved default provider/model\n4. known provider defaults (e.g. OpenAI/Anthropic/etc.) among available models\n5. first available model\n\n### Role aliases and settings\n\nSupported model roles:\n\n- `default` plus the agent assignment targets `executor`, `architect`, `planner`, `critic`\n\nRole aliases like `pi/default` expand through `settings.modelRoles`. Each role value can also append a thinking selector such as `:minimal`, `:low`, `:medium`, or `:high`.\n\nIf a role points at another role, the target model still inherits normally and any explicit suffix on the referring role wins for that role-specific use.\n\nRelated settings:\n\n- `modelRoles` (record)\n- `enabledModels` (scoped pattern list)\n- `modelProviderOrder` (global canonical-provider precedence)\n- `providers.kimiApiFormat` (`openai` or `anthropic` request format)\n- `providers.openaiWebsockets` (`auto|off|on` websocket preference for OpenAI code provider transport)\n\n`modelRoles` may store either:\n\n- `provider/modelId` to pin a concrete provider variant\n- a canonical id such as `gpt-5.3-openai-code` to allow provider coalescing\n\nFor `enabledModels` and CLI `--models`:\n\n- exact canonical ids expand to all concrete variants in that canonical group\n- explicit `provider/modelId` entries stay exact\n- globs and fuzzy matches still operate on concrete models\n\nGlobal `enabledModels` and `disabledProviders` entries may also be scoped to a path prefix:\n\n```yaml\nenabledModels:\n - anthropic-model-sonnet-4-5\n - path: ~/work\n models:\n - anthropic/anthropic-model-opus-4-5\ndisabledProviders:\n - ollama\n - path: ~/private\n providers:\n - anthropic\n```\n\nString entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. Use `path`, `paths`, `pathPrefix`, or `pathPrefixes`; use `models` for `enabledModels`, `providers` for `disabledProviders`, or `values` for either.\n\n## Fallback chains\n\nWhen the default model is blocked, the session walks an ordered chain of models instead of stopping. The chain for DEFAULT is built from:\n\n1. **The configured role value.** `modelRoles.default` may be one selector or an ordered array (`[anthropic/claude-opus-5-5:high, openai-codex/gpt-5.5]`); model profiles (`model_mapping`) and `task.agentModelOverrides` accept arrays the same way.\n2. **`fallback.models`**, a list you edit with `/fallback add <model>` / `remove <n>` / `clear`. It is independent of the head, so choosing another default in `/model` keeps it.\n3. **Automatic picks** (`fallback.auto`, on by default): one model from each other provider you are logged in to, up to three. Within a provider the model you used most recently wins, then the provider's curated default; a provider with neither is skipped rather than guessed. Providers already in the chain are not repeated, keyless local providers (Ollama, llama.cpp, LM Studio) are never added, and nothing is added while an `enabledModels` allow-list is in effect.\n\n`/fallback` prints the resulting chain, where each entry came from (`default`, `chain`, `added`, `auto`), and which one is in use. Settings → Model has **Automatic Model Fallback** and **Fallback Attempts per Model**.\n\nHow the chain is walked:\n\n- At the start of a prompt, entries whose provider has no usable credentials are skipped immediately (no request is sent), so a missing login moves straight to the next model. With nothing left to try, the error names the provider that lacks credentials and how to log in to it.\n- During a turn, an auth, quota, rate-limit, or server failure retries the current entry up to `fallback.maxAttempts` times (default 3), then advances. Every real switch emits `model_fallback_switched` and shows `Fallback model: from → to` in the status line.\n- Before moving to another model, a provider with several logged-in accounts hands the request to its next account. Settings → Providers → **Multi-Account Order** (`auth.credentialRankingMode`) picks the order: `balanced` (least-used first) or `earliest-reset` (the account whose usage window resets soonest). `SKC_CREDENTIAL_RANKING_MODE` overrides it per machine.\n- `retry.fallbackRevertPolicy` decides when to go back to the head: `cooldown-expiry` (default) retries it on a new turn once its suppression window ends; `never` stays on the fallback until you pick a model.\n\nAppended entries (`fallback.models` and automatic picks) live only in the running session; the configured chain the session records is not rewritten. A temporary model pick, an explicit `--model` at startup, and subagent chains composed by the task router run exactly as asked, without appended entries.\n\n## `/model` and `--list-models`\n\nBoth surfaces keep provider-prefixed models visible and selectable.\n\nThey now also expose canonical/coalesced models:\n\n- `/model` includes a canonical view alongside provider tabs\n- `--list-models` prints a canonical section plus the concrete provider rows\n\nSelecting a canonical entry stores the canonical selector. Selecting a provider row stores the explicit `provider/modelId`.\n\n### Assigning a model to a detailed use\n\nThe role rows in `/model` open a second level. The first level keeps its seven\nactions in their original order; picking `executor`, `architect`, `planner` or\n`critic` then offers **General (whole role)** plus the detailed uses that role\ncan actually run:\n\n| Role | Detailed uses |\n| --- | --- |\n| `planner`, `architect` | `backendArchitecture`, `frontendDesign` |\n| `executor` | `implementation`, `testing` |\n| `critic` | `review` |\n\n`default` has no detailed uses and still assigns in one keystroke. The two bulk\nrows write canonical role models only — they never touch detailed-use settings,\nbecause a \"set everything\" action that also rewrote five overrides could not be\nundone from the same menu.\n\nDetailed-use assignments persist to `task.modelRouting.specialtyModels`, a\nrecord whose keys are restricted to the five ids above; anything else is\nrejected by config validation. A row shows the model it already holds, and\n**Clear detailed-use overrides** removes only the entries belonging to that role.\n\nA saved detailed-use model is live immediately for any spawn that **declares**\nthat work (below). Saving one while `task.modelRouting.enabled` is `false` still\npersists it and says so; that switch only governs auto-detection.\n\n### How a subagent's model is chosen\n\nThere are two ways a detailed-use model reaches a spawn. The first is\ndeterministic and needs no switch; the second is a guess and only fires once\nthere are tiers configured for it to choose between.\n\n**Declared.** The `task` tool accepts `.specialty` per task — one of the five\nids above. When the user assigned a model to that specialty, the child runs on\nit. No classifier is consulted, `task.modelRouting.enabled` is not read, and no\nconfidence bar applies. The child leaves that model only when it **errors**:\nthe child session's fallback chain retries `fallback.maxAttempts` times on a\ntransport failure (429, 5xx, auth, quota) and then advances to the role's own\nchain composed behind it. The menu groups specialties under the roles that\nusually do that work, but the setting is one flat map, and a declared specialty\nignores that grouping on purpose: a frontend build delegated to `executor` with\n`specialty: \"frontendDesign\"` runs on the frontend model.\n\n**Auto-detected.** Without a declaration, routing needs\n`task.modelRouting.enabled` (on by default) **and** somewhere to route to: at\nleast two of `task.modelRouting.fastModel` / `balancedModel` / `deepModel`, or a\ndetailed-use entry, or the legacy `task.modelRouting.frontendModel`. The tiers\nare empty until you set them, so the default-on switch is a no-op for an\nunconfigured install. A single tier is not an axis — there is nowhere to move\nfrom it. It also needs typed decisions (`decisions.enabled`, on by default) and\na cheap model for the classifier to run on.\n\nOne classification runs per **child task**, not per `task` call. A batch shares\nan agent but not a workload, so an implementation slice and a test slice in the\nsame call are classified separately.\n\nEither way the result is dispatched as an ordered fallback chain, not a single\nmodel:\n\n1. the detailed-use model — declared, or picked by the classifier for a role that can run it\n2. the tier model, when the difficulty axis moved (auto-detected only)\n3. the role's own configured chain\n\nThe tail is always the role baseline, so a detailed-use model that cannot\nauthenticate still lands on something the role can actually run. A high-risk\nauto-detected assignment skips the detailed-use axis entirely and composes tier\nplus baseline only, because a lateral swap can move sideways into something\nweaker.\n\nReceipts record what the router **requested** separately from what the spawn ran\non. When the backend is an ordinary LLM it reports no probabilities at all, so\nthe receipt carries an ordinal clarity score and `calibrated: false` instead of\na fabricated confidence.\n\n## Context promotion (model-level fallback chains)\n\nContext promotion is an overflow recovery mechanism for small-context variants (for example `*-spark`) that automatically promotes to a larger-context sibling when the API rejects a request with a context length error. It is **off by default** (`contextPromotion.enabled` is `false`); opt in to enable it.\n\n### Trigger and order\n\nWhen a turn fails with a context overflow error (e.g. `context_length_exceeded`), `AgentSession` attempts promotion **before** falling back to compaction:\n\n1. If `contextPromotion.enabled` is true, resolve a promotion target (see below).\n2. If a target is found, switch to it and retry the request — no compaction needed.\n3. If no target is available, fall through to auto-compaction on the current model.\n\n### Target selection\n\nSelection is model-driven, not role-driven:\n\n1. `currentModel.contextPromotionTarget` (if configured)\n2. smallest larger-context model on the same provider + API\n\nCandidates are ignored unless credentials resolve (`ModelRegistry.getApiKey(...)`).\n\n### OpenAI code provider websocket handoff\n\nIf switching from/to `openai-codex-responses`, session provider state key `openai-codex-responses` is closed before model switch. This drops websocket transport state so the next turn starts clean on the promoted model.\n\n### Persistence behavior\n\nPromotion uses temporary switching (`setModelTemporary`):\n\n- recorded as a temporary `model_change` in session history\n- does not rewrite saved role mapping\n\n### Configuring explicit fallback chains\n\nConfigure fallback directly in model metadata via `contextPromotionTarget`.\n\n`contextPromotionTarget` accepts either:\n\n- `provider/model-id` (explicit)\n- `model-id` (resolved within current provider)\n\nExample (`models.yml`) for Spark -> non-Spark on the same provider:\n\n```yaml\nproviders:\n openai-code:\n modelOverrides:\n gpt-5.3-openai-code-spark:\n contextPromotionTarget: openai-code/gpt-5.3-openai-code\n```\n\nThe built-in model generator also assigns this automatically for `*-spark` models when a same-provider base model exists.\n\n## Compatibility and routing fields\n\nThe `compat` block on a provider or model overrides the URL-based auto-detection in `packages/ai/src/providers/openai-completions-compat.ts`. It is validated by `OpenAICompatSchema` in `packages/coding-agent/src/config/model-registry.ts` and consumed by every `openai-completions` transport (`packages/ai/src/providers/openai-completions.ts`). The canonical type is `OpenAICompat` in `packages/ai/src/types.ts`.\n\n`models.yml` accepts the following keys (all optional; unset falls back to URL detection):\n\nRequest shaping:\n\n- `supportsStore` — emit `store: false` on requests. Default: auto (off for non-standard endpoints).\n- `supportsDeveloperRole` — use the `developer` system role for reasoning models instead of `system`. Default: auto.\n- `sendSessionHeaders` — forward the agent session id as `session_id` and `x-session-id` request headers so OpenAI-compatible relays/proxies can do session-affinity routing and reuse a server-side prompt cache. Default: `false`. Caller-set `headers`/`requestTransform` values are never overwritten.\n- `supportsUsageInStreaming` — send `stream_options: { include_usage: true }` to receive token usage on streaming responses. Default: `true`.\n- `maxTokensField` — `\"max_completion_tokens\"` or `\"max_tokens\"`. Default: auto.\n- `supportsToolChoice` — emit the `tool_choice` parameter when the caller forces a specific tool. Default: `true`. Set `false` for endpoints that 400 on `tool_choice` (e.g. DeepSeek when reasoning is on).\n- `disableReasoningOnForcedToolChoice` — drop `reasoning_effort` / OpenRouter `reasoning` whenever `tool_choice` forces a call. Default: auto (Kimi/Anthropic-fronted endpoints).\n- `extraBody` — extra top-level fields merged into every request body (gateway hints, controller selectors, etc.).\n\nReasoning / thinking:\n\n- `supportsReasoningEffort` — accept `reasoning_effort`. Default: auto (off for zAI; on for Grok and OpenAI-compatible hosts that advertise it).\n- `reasoningEffortMap` — partial map from internal effort levels (`minimal|low|medium|high|xhigh`) to provider-specific strings (e.g. DeepSeek maps `xhigh -> \"max\"`).\n- `thinkingFormat` — request shape for thinking: `\"openai\"` (`reasoning_effort`), `\"openrouter\"` (`reasoning: { effort }`), `\"zai\"` (`thinking: { type: \"enabled\" }`), `\"qwen\"` (top-level `enable_thinking`), or `\"qwen-chat-template\"` (`chat_template_kwargs.enable_thinking`). Default: `\"openai\"`.\n- `reasoningContentField` — assistant field carrying chain-of-thought: `\"reasoning_content\"`, `\"reasoning\"`, or `\"reasoning_text\"`. Default: auto.\n- `requiresReasoningContentForToolCalls` — assistant tool-call turns must round-trip the reasoning field (DeepSeek-R1, Kimi, OpenRouter when reasoning is on). Default: `false`.\n- `requiresAssistantContentForToolCalls` — assistant tool-call turns must include non-empty text content (Kimi). Default: `false`.\n\nTool / message normalization:\n\n- `requiresToolResultName` — tool-result messages need a `name` field (Mistral). Default: auto.\n- `requiresAssistantAfterToolResult` — a user message after a tool result needs an assistant turn in between. Default: auto.\n- `requiresThinkingAsText` — convert thinking blocks to text wrapped in `<thinking>` delimiters (Mistral). Default: auto.\n- `requiresMistralToolIds` — normalize tool-call ids to exactly 9 alphanumeric chars. Default: auto.\n- `supportsStrictMode` — accept the per-tool `strict` field on tool schemas. Default: conservative auto-detect per provider/baseUrl.\n- `toolStrictMode` — `\"all_strict\"` forces strict on every tool, `\"none\"` forces it off; unset keeps the existing per-tool mixed behavior.\n\nGateway routing (only applied when `baseUrl` matches the gateway):\n\n- `openRouterRouting.only` / `openRouterRouting.order` — provider routing on `openrouter.ai` (see <https://openrouter.ai/docs/provider-routing>).\n- `vercelGatewayRouting.only` / `vercelGatewayRouting.order` — provider routing on `ai-gateway.vercel.sh` (see <https://vercel.com/docs/ai-gateway/models-and-providers/provider-options>).\n\nProvider-level `compat` is the baseline; per-model `compat` is deep-merged on top, with `openRouterRouting`, `vercelGatewayRouting`, and `extraBody` merged as nested objects.\n\n### Anthropic compatibility (`anthropic-messages`)\n\nFor `anthropic-messages` models the runtime uses a separate `AnthropicCompat` shape (`packages/ai/src/types.ts`). The `models.yml` schema currently exposes only the strict-tools opt-out as a top-level provider field (see below); the remaining Anthropic-side knobs (`disableAdaptiveThinking`, `supportsEagerToolInputStreaming`, `supportsLongCacheRetention`) are set by built-in catalog metadata and are not user-configurable from `models.yml`.\n\n### Strict tool schemas (`disableStrictTools`)\n\nAnthropic's API supports a `strict` field on tool definitions that forces the model to always follow the provided schema exactly. This is enabled by default for all `anthropic-messages` providers because it guarantees schema conformance in agentic systems.\n\nThird-party providers that front the Anthropic API (AWS Bedrock, Azure, self-hosted proxies) do not always implement this field and will reject requests that include it. Set `disableStrictTools: true` at the provider level to opt out:\n\n```yaml\nproviders:\n bedrock-anthropic:\n baseUrl: https://bedrock-runtime.us-east-1.amazonaws.com/anthropic\n apiKey: AWS_BEARER_TOKEN\n api: anthropic-messages\n disableStrictTools: true\n models:\n - id: anthropic-model-sonnet-4-20250514\n name: Anthropic model Sonnet 4 (Bedrock)\n input: [text, image]\n contextWindow: 200000\n maxTokens: 16384\n cost:\n input: 3.00\n output: 15.00\n cacheRead: 0.30\n cacheWrite: 3.75\n```\n\n`disableStrictTools` is a provider-level flag that applies to all models in the provider.\n\nTool schemas going on the wire are normalized by the unified flow in\n`packages/ai/src/utils/schema/normalize.ts` (Google/CCA/MCP dispatchers\nplus the OpenAI strict-mode sanitize+enforce pipeline). See\n[`ai-schema-normalize.md`](./ai-schema-normalize.md) for the strict-mode\nedge cases (local `$ref` inlining, single-item `allOf` collapse,\n`anyOf`-wrapper description hoist, enum/const primitive-type inference)\nand the per-provider dispatcher mapping.\n## Practical examples\n\n### Local OpenAI-compatible endpoint (no auth)\n\n```yaml\nproviders:\n local-openai:\n baseUrl: http://127.0.0.1:8000/v1\n auth: none\n api: openai-completions\n models:\n - id: Qwen/Qwen2.5-Coder-32B-Instruct\n name: Qwen 2.5 Coder 32B (local)\n```\n\n### Hosted proxy with env-based key\n\n```yaml\nproviders:\n anthropic-proxy:\n baseUrl: https://proxy.example.com/anthropic\n apiKey: ANTHROPIC_PROXY_API_KEY\n api: anthropic-messages\n authHeader: true\n disableStrictTools: true # if the proxy doesn't support strict tool schemas\n models:\n - id: anthropic-model-sonnet-4-20250514\n name: Anthropic model Sonnet 4 (Proxy)\n reasoning: true\n input: [text, image]\n```\n\n### Override built-in provider route + model metadata\n\n```yaml\nproviders:\n openrouter:\n baseUrl: https://my-proxy.example.com/v1\n headers:\n X-Team: platform\n modelOverrides:\n anthropic/anthropic-model-sonnet-4:\n name: Sonnet 4 (Corp)\n compat:\n openRouterRouting:\n only: [anthropic]\n```\n\n## Legacy consumer caveat\n\nMost model configuration now flows through `models.yml` via `ModelRegistry`. Explicit `.json` / `.jsonc` paths remain supported only when passed programmatically to `ModelRegistry`; the default user config is `~/.skc/agent/models.yml`.\n\n## Failure mode\n\nIf `models.yml` fails schema or validation checks:\n\n- registry keeps operating with built-in models\n- error is exposed via `ModelRegistry.getError()` and surfaced in UI/notifications\n",
|
|
42
43
|
"multi-vendor-profiles.md": "# Choosing models in SKC: role-based profiles\n\nA practical guide to picking models for SKC's roles, for every subscription situation — one vendor, two vendors, or the full multi-vendor set. It adds curated cross-vendor `profiles:` for `~/.skc/agent/models.yml` and verified selector notes on top of the mechanism in [Model profiles](./models.md#model-profiles---mpreset). Everything here is **user config**; it complements the built-in `--mpreset` presets and overrides a built-in only when it shares its exact name.\n\n> Selectors, prices, and \"axis leaders\" are catalog- and time-sensitive (selectors and prices observed 2026-07 on the current bundled catalog; the measured latency and single-message-limit notes below were observed 2026-06 on `claude-opus-4-8` and have not been re-measured on `claude-opus-5`). Re-verify any selector with `skc -p --no-session --no-tools --model <selector> \"Reply OK\"`.\n\n## The five roles\n\n`default` runs the main loop and most turns; `executor` / `architect` / `planner` / `critic` are the four bundled task agents, delegated only when the work calls for it.\n\n| Role | What it optimizes for |\n| --- | --- |\n| `default` | tool-calling reliability + honesty (it routes — its quality bounds the whole system) |\n| `executor` | real coding (SWE-bench Verified) |\n| `planner` | reasoning + sequencing (GPQA / ARC-AGI-2) |\n| `architect` | large-context + multimodal review |\n| `critic` | independent adversarial review (different family from what it reviews) |\n\n## Pick by what you subscribe to\n\n| You have | Use |\n| --- | --- |\n| **One vendor** | the built-in preset for that vendor — `claude-opus-5-5` or `claude-opus` (Anthropic), `codex-{eco,medium,pro}` (OpenAI/Codex), `opencodego` (OpenCode Go), or a single-vendor flagship tier (`zai/glm-5.2`, `kimi-code/...`, `xiaomi/...`, `xai/grok-4.6`, `minimax-code/...`). These already map all five roles inside one vendor. |\n| **Claude + Codex** | the built-in `opus-codex` (Claude main loop + Codex support roles). |\n| **Three or more / all five** | the cross-vendor profiles below — each role on its axis leader, `critic` kept cross-family. |\n\nThe single guiding rule across all of these: **keep `default` on the strongest router you have** (Anthropic Opus when available). A weak `default` caps quality regardless of the delegated models.\n\n## Cross-vendor profiles (3+ vendors)\n\nNo single vendor leads every axis, so these put each role on its axis leader and keep `critic` on a different family from the `executor` it reviews.\n\n```yaml\nprofiles:\n\n daily: # everyday balance\n required_providers: [anthropic, openai-codex, google-antigravity, xai]\n model_mapping:\n default: anthropic/claude-opus-5:medium\n executor: openai-codex/gpt-5.4:high\n planner: google-antigravity/gemini-3.1-pro-low:high\n architect: google-antigravity/gemini-3.1-pro-low:high\n critic: xai/grok-4.6:medium\n\n ultimate: # cost-no-object, best per role\n required_providers: [anthropic, openai-codex, google-antigravity, xai]\n model_mapping:\n default: anthropic/claude-opus-5:high\n executor: anthropic/claude-opus-5:max\n planner: openai-codex/gpt-5.5:xhigh\n architect: google-antigravity/gemini-3.1-pro-low:high\n critic: xai/grok-4.6:high\n\n eco: # cheapest delegated work; main loop stays on Opus\n required_providers: [anthropic, opencode-go, google-antigravity, xai]\n model_mapping:\n default: anthropic/claude-opus-5:low\n executor: opencode-go/deepseek-v4-flash\n planner: xai/grok-4-1-fast:high\n architect: google-antigravity/gemini-3.1-pro-low\n critic: google-antigravity/gemini-3.5-flash\n\n monorepo: # huge codebases (openai-codex excluded: 272k context cap)\n required_providers: [anthropic, google-antigravity, opencode-go]\n model_mapping:\n default: anthropic/claude-opus-5:medium\n executor: anthropic/claude-opus-5:high\n planner: google-antigravity/gemini-3.1-pro-low:high\n architect: anthropic/claude-opus-5:high\n critic: opencode-go/glm-5.2\n\n reviewer: # review/audit stance — the author-mode role split, inverted\n required_providers: [anthropic, openai-codex, google-antigravity]\n model_mapping:\n default: anthropic/claude-opus-5:high # aggregator restraint: preserve raw reviewer verdicts\n executor: openai-codex/gpt-5.5:high # support — repro PoCs, failing tests, harnesses\n planner: google-antigravity/gemini-3.1-pro-low:high # review checklists / audit scoping\n architect: anthropic/claude-opus-5:high # lead 1 — primary code-review judge (effective long-context)\n critic: openai-codex/gpt-5.5:high # lead 2 — merge gate, cross-family vs Claude-authored code\n```\n\n## Model cheatsheet (by need)\n\nCurrent axis leaders and the cheaper second option, with metered price ($/1M in/out; Gemini via Antigravity runs on the Google AI subscription):\n\n| Need | First pick | Cheaper option |\n| --- | --- | --- |\n| Router / tool-calling (`default`) | `anthropic/claude-opus-5` (5/25) | `anthropic/claude-sonnet-5` (3/15) |\n| Coding (`executor`) | `anthropic/claude-opus-5` (5/25) — the prior `claude-opus-4-8` scored SWE-bench Verified ~88.6; no Opus 5 measurement yet | `openai-codex/gpt-5.4` (2.5/15) · `opencode-go/deepseek-v4-flash` (0.14/0.28) |\n| Reasoning (`planner`) | `openai-codex/gpt-5.5` (ARC-AGI-2) / `google-antigravity/gemini-3.1-pro-low:high` (GPQA) | `xai/grok-4-1-fast` (0.2/0.5) |\n| Large context (`architect`) | `anthropic/claude-opus-5` (effective long-context) | `xai/grok-4-fast` (2M nominal, 0.2/0.5) |\n| Multimodal review (`architect`) | `google-antigravity/gemini-3.1-pro-low:high` | `google-antigravity/gemini-3.5-flash` |\n| Independent critic | `xai/grok-4.6` (2/6) | `opencode-go/glm-5.2` · `google-antigravity/gemini-3.5-flash` |\n\nOn standard tasks, all current frontier models in the catalog are accurate; **pick by cost, latency, and role fit, not by raw accuracy on easy prompts.** As an indicative SKC-routed latency reference (`skc -p`, identical coding + reasoning prompts, all correct): `grok-4.6` / `grok-4.3` and `glm-5.2` ≈ 2–3s, `deepseek-v4-pro` ≈ 3–4s, `claude-opus-4-8` / `gpt-5.5` ≈ 4–7s, `gemini-3.1-pro-low:high` ≈ 7s. `claude-opus-5` shares Opus 4.8's published context/output envelope but has not been latency-measured here.\n\n## Verified selector notes (current catalog)\n\nObserved via live `skc -p` calls; useful when wiring the profiles above:\n\n- **Antigravity Gemini, high reasoning** → use `google-antigravity/gemini-3.1-pro-low:high`. The id `gemini-3.1-pro-high` returns HTTP 400 (no matching backend model); `thinkingLevel` is a per-request parameter, so raising it on `gemini-3.1-pro-low` invokes the model's native high-reasoning mode rather than a degraded one.\n- **openai-codex on a ChatGPT account** serves base GPT only (`gpt-5.5`, `gpt-5.4`). Standalone `-codex` variants (`gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-max` / `-mini`) return `not supported when using Codex with a ChatGPT account`.\n- **Single-message input limit is separate from the context window.** Measured on `claude-opus-4-8` (not yet re-measured on `claude-opus-5`, which publishes the same 1M window): the model runs with a 1M window via multi-turn accumulation, but a single `@file` message above ~400k tokens returns 400 on `anthropic` / `google-antigravity`; `xai` / `opencode-go` accept larger single messages. Chunk very large inputs across turns instead of pasting one block.\n- **Some selectors come from a provider's live catalog, not the bundled snapshot.** `opencode-go/glm-5.2` and `google-antigravity/gemini-3.5-flash` resolved in `skc -p` tests but are **not** in `packages/ai/src/models.json`; they appear only after the provider's online model discovery has populated the registry. `required_providers` verifies credentials at activation — it does **not** guarantee fresh, non-stale discovery — so activation can still fail with `selector did not resolve` until discovery runs (re-login or retry to refresh). If you hit that, substitute a bundled id: `opencode-go/deepseek-v4-pro` for the critic, or `zai/glm-5.2` (add `zai` to `required_providers`) for GLM 5.2.\n\n## Activation\n\n```bash\nskc --mpreset daily # this session only\nskc --mpreset ultimate --default # persist as the startup default (config.yml)\n```\n\nActivation hard-blocks when any provider in `required_providers` lacks credentials, so log in first: `/login anthropic`, `/login openai-codex`, `/login google-antigravity`, `/login xai` (and `opencode-go` via `OPENCODE_API_KEY`).\n",
|
|
43
44
|
"native-ffi-optimization-policy.md": "# ADR: Native FFI Optimization Policy\n\n- Status: Accepted\n- Scope: `crates/pi-natives` algorithmic ports proposed for performance reasons\n- Related: [`porting-to-natives.md`](./porting-to-natives.md), [`natives-architecture.md`](./natives-architecture.md), [`natives-binding-contract.md`](./natives-binding-contract.md), [`cpu-hotspot-map.json`](./cpu-hotspot-map.json), [`hotspot-map-successor.md`](./hotspot-map-successor.md)\n\n## Decision\n\nA new native (Rust N-API / FFI) port proposed **to optimize a leftover hot path** does not land unless **all** of the following gates pass:\n\n1. **Corpus evidence** — a profiling-corpus trace shows the path has user-visible latency or RSS impact on a representative workload (not just a static complexity argument).\n2. **Self-time attribution** — a `profilerSelfTime` artifact identifies the proposed hotspot, **or** fallback-toggle evidence proves an end-to-end benefit without byte changes. Wall-clock proxy timing alone is never sufficient.\n3. **Measured FFI overhead** — the N-API call/marshalling overhead is measured against the JS/TS baseline, not assumed away.\n4. **Representative win** — a representative p50/p95 win exists on realistic inputs, not only microbenchmark seed results.\n5. **Byte parity** — a byte-identical corpus covers rendered, persisted, and provider-visible bytes for the changed path.\n6. **Operational cost** — fallback, packaging, and rollback costs are documented.\n\nThis policy governs **speculative algorithmic ports**. It does **not** re-litigate already-native platform/system surfaces (see [Scope boundary](#scope-boundary)).\n\n## Context\n\nThe CPU/memory hotspot program (Optimization Suites v1–v3, tracked in [`cpu-hotspot-map.json`](./cpu-hotspot-map.json)) is closed out. Its prioritization was a **static structural ranking** (algorithmic complexity × trigger frequency), and the map's own `method` field records that real CPU self-time was \"to be measured by the agreed profiling corpus during optimization.\" That corpus is being built separately; until its evidence exists, new native ports for leftover hotspots would repeat the same evidence gap.\n\nThe suites already produced concrete decisions that this policy codifies so they are not re-discovered:\n\n- **v2 (#530)** measured and **rejected the five remaining Rust port candidates** per the FFI cost gates after shipping only `diffLines` (H03) natively. Native overhead did not beat the JS/TS baseline for those candidates on realistic inputs.\n- **v3 (#558) rejected a native word-diff (H04)** \"without a fresh FFI gate\" — the TS fast paths were retained instead; a native port would need to re-clear gates 1–6 above.\n- **Hunt-Szymanski LCS (H05)** was implemented as a native/algorithmic replacement, then **reverted** because it produced byte-different rendered diffs (reproduced by red-team). Byte parity is the gate, not raw speed.\n- **The custom JSON length counter (H08)** was implemented, made exact, then **deleted** — an exact JS reimplementation was not faster than native `JSON.stringify`. \"More native\" is not automatically \"faster.\"\n\nThese four precedents share a root cause: a plausible algorithmic/native win that failed a real gate (cost, byte parity, or end-to-end benefit). The policy makes those gates a precondition rather than a post-hoc discovery.\n\n## Evidence taxonomy\n\nNative-port claims must classify their evidence using the same separated classes as the profiling corpus. These classes must never be conflated:\n\n- **`wallClockPhase`** — elapsed timing around a phase or operation. Useful for perceived-latency and regression detection; **insufficient** to confirm CPU self-time or to justify a port on its own.\n- **`processCpuUsage`** — `process.cpuUsage()` user/system deltas, optionally normalized by elapsed time. Indicates process-level CPU pressure; **cannot** attribute self-time to a specific hotspot.\n- **`profilerSelfTime`** — profiler (or equivalent sampled/trace) attribution of self-time to a function, module, or native symbol. **Required** before a hotspot may be called \"CPU-self-time confirmed.\"\n\nA native-optimization proposal that cites only `wallClockPhase` or `processCpuUsage` is **not** CPU-self-time confirmed and does not clear gate 2.\n\n## Approval checklist\n\nBefore opening a native-optimization PR, confirm and attach evidence for each:\n\n- [ ] Corpus trace shows user-visible latency or RSS impact for the path (gate 1).\n- [ ] `profilerSelfTime` artifact identifies the hotspot, **or** fallback-toggle before/after evidence proves end-to-end benefit without byte changes (gate 2).\n- [ ] FFI/marshalling overhead measured vs the JS/TS baseline in the same benchmark run (gate 3).\n- [ ] Representative p50/p95 win on realistic inputs, not only seeded microbench results (gate 4).\n- [ ] Byte-identical corpus covers rendered, persisted, and provider-visible bytes (gate 5).\n- [ ] Fallback, packaging (platform variants / embedded addon), and rollback costs documented (gate 6).\n\nIf any box is unchecked, keep the work in TypeScript or hold it as a tracked candidate; do not switch callsites. This mirrors the existing **Rule of thumb** in [`porting-to-natives.md`](./porting-to-natives.md): if native is not faster *and* behavior-compatible, do not switch callsites.\n\n## Scope boundary\n\nThis policy targets **speculative algorithmic ports**, not the established native surface. The following are **already native** by design and are explicitly out of scope (see `alreadyNativeExcluded` in [`cpu-hotspot-map.json`](./cpu-hotspot-map.json)):\n\n`grep`, `fd`/`glob`, text width/wrap/truncate/slice, syntax highlighting, HTML→Markdown, token counting, AST, summary, process/PTY/shell, SIXEL, clipboard, `Bun.hash.xxHash32/64`, and `JSON.parse`/`JSON.stringify`.\n\nThese are native because they are I/O, OS/process integration, or platform primitives — the criteria in [`porting-to-natives.md`](./porting-to-natives.md#when-to-port). Distinguishing them from algorithmic ports matters: a leftover algorithmic hotspot must clear gates 1–6, whereas adding a new OS/process/native-primitive binding follows the standard porting guide.\n\n## Consequences\n\n- New native algorithmic ports require profiling-corpus evidence and a measured cost gate before review; this slows speculative optimization but prevents byte-parity regressions and dead native code.\n- The default answer for a leftover hotspot is \"keep it in TypeScript\" until the corpus proves it matters.\n- Already-native platform/system primitives and new OS/process bindings are unaffected; they follow [`porting-to-natives.md`](./porting-to-natives.md) as before.\n- Reviewers can reject a native-optimization PR purely on a missing gate, citing this ADR, without re-deriving the rationale.\n\n## Follow-ups\n\n- Held native candidates (H04 word-diff, H05 LCS, and other v2-rejected candidates) stay held unless a future PR clears gates 1–6 with fresh corpus evidence.\n- When the profiling corpus lands, link its threshold/evidence ledger here so native-port proposals can cite concrete corpus artifacts.\n",
|
|
@@ -69,12 +70,12 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
|
|
|
69
70
|
"prompt-architect-reports/tool-prompts.raw.md": "# ToolPrompts recovered raw report\n\nThe original `agent://0-ToolPrompts` result surfaced as failed, but inspecting the subagent JSONL context recovered 34 structured `report_finding` entries before the session died on stalls/429.\n\nCanonical recovered artifacts:\n\n- `recovered-context/0-ToolPrompts.recovered.md`\n- `recovered-context/0-ToolPrompts.findings.json`\n- `recovery-summary.md`\n\nRecovered severity breakdown: P1 = 4, P2 = 18, P3 = 12. No final `yield` or grade was emitted.\n",
|
|
70
71
|
"provider-streaming-internals.md": "# Provider streaming internals\n\nThis document explains how token/tool streaming is normalized in `@sayknow-cli/ai`, then propagated through `@sayknow-cli/agent-core` and `coding-agent` session events.\n\n## End-to-end flow\n\n1. `streamSimple()` (`packages/ai/src/stream.ts`) maps generic options and dispatches to a provider stream function.\n2. Provider stream functions translate provider-native stream events into the unified `AssistantMessageEvent` sequence. Current built-ins include Anthropic, OpenAI Responses/Completions/OpenAI code/Azure Responses, Google Gemini/Gemini CLI/Vertex, Bedrock Converse, Ollama, Cursorand GitLab Duo/Kimi wrappers.\n3. Each provider pushes events into `AssistantMessageEventStream` (`packages/ai/src/utils/event-stream.ts`), which throttles delta events and exposes:\n - async iteration for incremental updates\n - `result()` for final `AssistantMessage`\n4. `agentLoop` (`packages/agent/src/agent-loop.ts`) consumes those events, mutates in-flight assistant state, and emits `message_update` events carrying the raw `assistantMessageEvent`.\n5. `AgentSession` (`packages/coding-agent/src/session/agent-session.ts`) subscribes to agent events, persists messages, and applies session behaviors (retry, compaction, TTSR, streaming-edit abort checks).\n\n## Unified stream contract in `@sayknow-cli/ai`\n\nAll providers emit the same shape (`AssistantMessageEvent` in `packages/ai/src/types.ts`):\n\n- `start`\n- content block lifecycle triplets:\n - text: `text_start` → `text_delta`\\* → `text_end`\n - thinking: `thinking_start` → `thinking_delta`\\* → `thinking_end`\n - tool call: `toolcall_start` → `toolcall_delta`\\* → `toolcall_end`\n- terminal event:\n - `done` with `reason: \"stop\" | \"length\" | \"toolUse\"`\n - or `error` with `reason: \"aborted\" | \"error\"`\n\n`AssistantMessageEventStream` guarantees:\n\n- final result is resolved by terminal event (`done` or `error`)\n- deltas are batched/throttled (~50ms)\n- buffered deltas are flushed before non-delta events and before completion\n\n## Delta throttling and harmonization behavior\n\n`AssistantMessageEventStream` treats `text_delta`, `thinking_delta`, and `toolcall_delta` as mergeable events:\n\n- buffered deltas are merged only when **type + contentIndex** match\n- merge keeps the latest `partial` snapshot\n- non-delta events force immediate flush\n\nThis smooths high-frequency provider streams for TUI/event consumers, but is not provider backpressure: providers still produce at full speed, while the local stream buffers.\n\n## Provider normalization details\n\n## Anthropic (`anthropic-messages`)\n\nSource: `packages/ai/src/providers/anthropic.ts`\n\nNormalization points:\n\n- `message_start` initializes usage (input/output/cache tokens)\n- `content_block_start` maps to text/thinking/toolcall starts\n- `content_block_delta` maps:\n - `text_delta` → `text_delta`\n - `thinking_delta` → `thinking_delta`\n - `input_json_delta` → `toolcall_delta`\n - `signature_delta` updates `thinkingSignature` only (no event)\n- `content_block_stop` emits corresponding `*_end`\n- `message_delta.stop_reason` maps via `mapStopReason()`\n\nTool-call argument streaming:\n\n- each tool block carries internal `partialJson`\n- every JSON delta appends to `partialJson`\n- `arguments` are reparsed on each delta via `parseStreamingJson()`\n- `toolcall_end` reparses once more, then strips `partialJson`\n\n## OpenAI Responses family (`openai-responses`, `openai-code-responses`, `azure-openai-responses`)\n\nSources: `packages/ai/src/providers/openai-responses.ts`, `openai-code-responses.ts`, and `azure-openai-responses.ts`\n\nNormalization points:\n\n- `response.output_item.added` starts reasoning/text/function-call blocks\n- reasoning summary events (`response.reasoning_summary_text.delta`) become `thinking_delta`\n- output/refusal deltas become `text_delta`\n- `response.function_call_arguments.delta` becomes `toolcall_delta`\n- `response.output_item.done` emits `thinking_end` / `text_end` / `toolcall_end`\n- `response.completed` maps status to stop reason and usage\n\nTool-call argument streaming:\n\n- same `partialJson` accumulation pattern as Anthropic\n- providers that send only `response.function_call_arguments.done` still populate final args\n- tool call IDs are normalized as `\"<call_id>|<item_id>\"`\n\n## Google Generative AI (`google-generative-ai`)\n\nSource: `packages/ai/src/providers/google.ts`\n\nNormalization points:\n\n- iterates `candidate.content.parts`\n- text parts are split into thinking vs text by `isThinkingPart(part)`\n- block transitions close previous block before starting a new one\n- `part.functionCall` is treated as a complete tool call (start/delta/end emitted immediately)\n- finish reason mapped by `mapStopReason()` from `google-shared.ts`\n\nTool-call argument streaming:\n\n- function call args arrive as structured object, not incremental JSON text\n- implementation emits one synthetic `toolcall_delta` containing `JSON.stringify(arguments)`\n- no partial JSON parser needed for Google in this path\n\n## Partial tool-call JSON accumulation and recovery\n\nShared behavior for Anthropic/OpenAI Responses uses `parseStreamingJson()` (`packages/ai/src/utils/json-parse.ts`):\n\n1. try `JSON.parse`\n2. fallback to `partial-json` parser for incomplete fragments\n3. if both fail, return `{}`\n\nImplications:\n\n- malformed or truncated argument deltas do not crash stream processing immediately\n- in-progress `arguments` may temporarily be `{}`\n- later valid deltas can recover structured arguments because parsing is retried on every append\n- final `toolcall_end` performs one more parse attempt before emission\n\n## Stop reasons vs transport/runtime errors\n\nProvider stop reasons are mapped to normalized `stopReason`:\n\n- Anthropic: `end_turn`→`stop`, `max_tokens`→`length`, `tool_use`→`toolUse`, safety/refusal cases→`error`\n- OpenAI Responses: `completed`→`stop`, `incomplete`→`length`, `failed/cancelled`→`error`\n- Google: `STOP`→`stop`, `MAX_TOKENS`→`length`, safety/prohibited/malformed-function-call classes→`error`\n\nError semantics are split in two stages:\n\n1. **Model completion semantics** (provider reported finish reason/status)\n2. **Transport/runtime failure** (network/client/parser/abort exceptions)\n\nIf provider stream throws or signals failure, each provider wrapper catches and emits terminal `error` event with:\n\n- `stopReason = \"aborted\"` when abort signal is set\n- otherwise `stopReason = \"error\"`\n- `errorMessage = formatErrorMessageWithRetryAfter(error)`\n\n## Malformed chunk / SSE parse failure behavior\n\nFor these provider paths, chunk/SSE framing is handled by vendor SDK streams (Anthropic SDK, OpenAI SDK, Google SDK). This code does not implement a custom SSE decoder here.\n\nObserved behavior in current implementation:\n\n- malformed chunk/SSE parsing at SDK level surfaces as an exception or stream `error` event\n- provider wrapper converts that into unified terminal `error` event\n- no provider-specific resume/retry inside the stream function itself\n- higher-level retries are handled in `AgentSession` auto-retry logic (message-level retry, not stream-chunk replay)\n\n## Cancellation boundaries\n\nCancellation is layered:\n\n- AI provider request: `options.signal` is passed into provider client stream call.\n- Provider wrapper: after stream loop, aborted signal forces error path (`\"Request was aborted\"`).\n- Agent loop: checks `signal.aborted` before handling each provider event and can synthesize an aborted assistant message from the latest partial.\n- Session/agent controls: `AgentSession.abort()` -> `agent.abort()` -> shared abort controller cancellation.\n\nTool execution cancellation is separate from model stream cancellation:\n\n- tool runners use `AbortSignal.any([agentSignal, steeringAbortSignal])`\n- steering interrupts can abort remaining tool execution while preserving already-produced tool results\n\n## Backpressure boundaries\n\nThere is no hard backpressure mechanism between provider SDK stream and downstream consumers:\n\n- `EventStream` uses in-memory queues with no max size\n- throttling reduces UI update rate but does not slow provider intake\n- if consumers lag significantly, queued events can grow until completion\n\nCurrent design favors responsiveness and simple ordering over bounded-buffer flow control.\n\n## How stream events surface as agent/session events\n\n`agentLoop.streamAssistantResponse()` bridges `AssistantMessageEvent` to `AgentEvent`:\n\n- on `start`: pushes placeholder assistant message and emits `message_start`\n- on block events (`text_*`, `thinking_*`, `toolcall_*`): updates last assistant message, emits `message_update` with raw `assistantMessageEvent`\n- on terminal (`done`/`error`): resolves final message from `response.result()`, emits `message_end`\n\n`AgentSession` then consumes those events for session-level behaviors:\n\n- TTSR watches `message_update.assistantMessageEvent` for `text_delta`, `thinking_delta`, and `toolcall_delta`\n- streaming edit guard inspects `toolcall_delta`/`toolcall_end` on `edit` calls and can abort early\n- persistence writes finalized messages at `message_end`\n- auto-retry examines assistant `stopReason === \"error\"` plus `errorMessage` heuristics\n\n## Unified vs provider-specific responsibilities\n\nUnified (common contract):\n\n- event shape (`AssistantMessageEvent`)\n- final result extraction (`done`/`error`)\n- delta throttling + merge rules\n- agent/session event propagation model\n\nProvider-specific (not fully abstracted):\n\n- upstream event taxonomies and mapping logic\n- stop-reason translation tables\n- tool-call ID conventions\n- reasoning/thinking block semantics and signatures\n- usage token semantics and availability timing\n- message conversion constraints per API\n\n## Implementation files\n\n- [`../../ai/src/stream.ts`](../packages/ai/src/stream.ts) — provider dispatch, option mapping, API key/session plumbing, custom API dispatch, and provider-specific credential handling.\n- [`../../ai/src/utils/event-stream.ts`](../packages/ai/src/utils/event-stream.ts) — generic stream queue + assistant delta throttling.\n- [`../../ai/src/utils/json-parse.ts`](../packages/ai/src/utils/json-parse.ts) — partial JSON parsing for streamed tool arguments.\n- [`../../ai/src/providers/anthropic.ts`](../packages/ai/src/providers/anthropic.ts) — Anthropic event translation and tool JSON delta accumulation.\n- [`../../ai/src/providers/openai-responses.ts`](../packages/ai/src/providers/openai-responses.ts), [`openai-code-responses.ts`](../packages/ai/src/providers/openai-code-responses.ts), [`azure-openai-responses.ts`](../packages/ai/src/providers/azure-openai-responses.ts) — Responses-family event translation and status mapping.\n- [`../../ai/src/providers/google.ts`](../packages/ai/src/providers/google.ts), [`google-gemini-cli.ts`](../packages/ai/src/providers/google-gemini-cli.ts), [`google-vertex.ts`](../packages/ai/src/providers/google-vertex.ts) — Gemini stream chunk-to-block translation variants.\n- [`../../ai/src/providers/google-shared.ts`](../packages/ai/src/providers/google-shared.ts) — Gemini finish-reason mapping and shared conversion rules.\n- [`../../ai/src/providers/amazon-bedrock.ts`](../packages/ai/src/providers/amazon-bedrock.ts), [`openai-completions.ts`](../packages/ai/src/providers/openai-completions.ts), [`ollama.ts`](../packages/ai/src/providers/ollama.ts), [`cursor.ts`](../packages/ai/src/providers/cursor.ts) — additional built-in stream adapters using the same event contract.\n- [`../../agent/src/agent-loop.ts`](../packages/agent/src/agent-loop.ts) — provider stream consumption and `message_update` bridging.\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts) — session-level handling of streaming updates, abort, retry, and persistence.\n",
|
|
71
72
|
"python-repl.md": "# Eval Tool Python Backend\n\nThis document describes the Python execution stack in `packages/coding-agent`.\nIt covers tool behavior, runner lifecycle, environment handling, execution semantics, output rendering, supported magics, and operational failure modes.\n\n## Scope and Key Files\n\n- Tool surface: `src/tools/eval.ts`\n- Session/per-call kernel orchestration: `src/eval/py/executor.ts`\n- Subprocess kernel client: `src/eval/py/kernel.ts`\n- Python wrapper / NDJSON server: `src/eval/py/runner.py`\n- Prelude helpers loaded into every kernel: `src/eval/py/prelude.py`\n- MIME bundle renderer (text + structured outputs): `src/eval/py/display.ts`\n- Interactive-mode renderer for user-triggered Python runs: `src/modes/components/eval-execution.ts`\n- Runtime/env filtering and Python resolution: `src/eval/py/runtime.ts`\n\n## What eval's Python backend is\n\nThe `eval` tool executes one or more Python cells inside a long-lived `python3` subprocess that speaks NDJSON over stdin/stdout. No Jupyter, no kernel gateway, no extra pip dependencies — a vanilla Python 3.8+ interpreter is enough. Rich `display()` output (PIL, pandas, plotly, matplotlib figures) keeps working because the wrapper reimplements the MIME-bundle dispatch that IPython previously provided.\n\nTool params:\n\n```ts\n{\n cells: Array<{ code: string; title?: string }>;\n timeout?: number; // seconds, clamped to 1..600, default 30\n reset?: boolean; // reset selected runtime before the first cell only\n}\n```\n\nThe tool is `concurrency = \"exclusive\"` for a session, so calls do not overlap.\n\n## Kernel lifecycle\n\nEach kernel is a single Python subprocess: `python -u <runner.py>`. The bundled runner is materialized once per SKC process in a process-private temporary directory and file, then reused only by subsequent spawns within that process.\n\nKernel startup sequence:\n\n1. Availability check (`checkPythonKernelAvailability`) — verifies that a Python interpreter resolves and runs.\n2. Spawn `python -u runner.py` with filtered env and `cwd`.\n3. Send an init request that runs `os.chdir(cwd)`, injects env entries, and adds `cwd` to `sys.path`.\n4. Execute `PYTHON_PRELUDE` (idempotent — only initializes once per process).\n\nKernel shutdown:\n\n- Send `{\"type\": \"exit\"}` over stdin.\n- Wait for process exit with `SHUTDOWN_GRACE_MS` budget.\n- Escalate to `SIGTERM` and finally `SIGKILL` if the process does not exit in time.\n\n## Wire protocol (NDJSON, host ↔ runner)\n\nOne JSON object per line, UTF-8, `\\n` terminated.\n\nHost → runner:\n\n```jsonc\n{\"id\": \"<reqId>\", \"code\": \"<source>\", \"silent\": false, \"storeHistory\": true}\n{\"type\": \"exit\"}\n```\n\nRunner → host:\n\n```jsonc\n{\"type\": \"started\", \"id\": \"<reqId>\"}\n{\"type\": \"stdout\", \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"stderr\", \"id\": \"<reqId>\", \"data\": \"...\"}\n{\"type\": \"display\", \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"result\", \"id\": \"<reqId>\", \"bundle\": {<mime>: <value>}}\n{\"type\": \"error\", \"id\": \"<reqId>\", \"ename\": \"...\", \"evalue\": \"...\", \"traceback\": [\"...\"]}\n{\"type\": \"done\", \"id\": \"<reqId>\", \"status\": \"ok\"|\"error\", \"executionCount\": N, \"cancelled\": false}\n```\n\nStatus events the prelude emits (e.g. `_emit_status(\"find\", count=…)`) ship inside display bundles under `application/x-skc-status` so the existing TUI status renderer keeps working.\n\n## Magics\n\nThe runner's source transformer rewrites IPython-style magics to plain Python calls before parsing. Supported set:\n\n| Magic | Effect |\n| --- | --- |\n| `%pip <args>` | `python -m pip <args>` with live streaming output. Newly installed packages are evicted from `sys.modules` so the next `import` picks up the fresh install. |\n| `%cd <path>` | `os.chdir(path)` (with `~` expansion); emits status event. |\n| `%pwd` | Returns `os.getcwd()`. |\n| `%ls [path]` | Returns `sorted(os.listdir(path))`. |\n| `%env [KEY[=VAL]]` | List, read, or set env vars (matches prelude `env()` semantics). |\n| `%set_env KEY VALUE` | Set `os.environ[KEY]`. |\n| `%time <expr>` / `%timeit <expr>` | Time the expression; emits status event with elapsed ms. |\n| `%who` / `%whos` | List user-namespace names. |\n| `%reset` | Clear user globals and re-inject prelude. |\n| `%load <path>` | Read a file into a fresh cell and execute. |\n| `%run <path>` | `runpy.run_path` and merge globals back. |\n| `%%bash` / `%%sh` | Run the cell body via `bash`/`sh`. |\n| `%%capture [name]` | Run body with stdout/stderr captured into `name`. |\n| `%%timeit` | Time the cell body. |\n| `%%writefile <path>` | Write body to file. |\n| `!cmd` / `var = !cmd` | Run command via subprocess shell; returns an SList-style result with `.n` / `.s` helpers. |\n| `var = %name args` | Assignment forms work for line magics and `!cmd`. |\n\nUnknown magic names raise `NameError: UsageError: ...` inside the cell.\n\n## Session persistence semantics\n\n`python.kernelMode` controls retained kernel reuse:\n\n- `session` (default)\n - Reuses kernel sessions keyed by session file plus cwd when a session file exists; otherwise by cwd.\n - Execution is serialized per session via a queue.\n - Idle sessions are evicted after 5 minutes.\n - At most 4 sessions; oldest is evicted on overflow.\n - Heartbeat checks detect dead kernels.\n - Auto-restart allowed once; repeated crash ⇒ hard failure.\n- `per-call`\n - Spawns a fresh subprocess for each request.\n - Shuts the subprocess down after the request.\n - No cross-call state persistence.\n\n### Multi-cell behavior in a single tool call\n\nCells run sequentially in the same kernel instance for that tool call.\n\nIf an intermediate cell fails:\n\n- Earlier cell state remains in memory.\n- Tool returns a targeted error indicating which cell failed.\n- Later cells are not executed.\n\n`reset=true` only applies to the first cell execution in that call.\n\n## Environment filtering and runtime resolution\n\nEnvironment is filtered before launching the runner:\n\n- Allowlist includes core vars like `PATH`, `HOME`, locale vars, `VIRTUAL_ENV`, `PYTHONPATH`, etc.\n- Allow-prefixes: `LC_`, `XDG_`, `SKC_`\n- Denylist strips common API keys (OpenAI/Anthropic/Gemini/etc.)\n\nRuntime selection order:\n\n1. Active/located venv (`VIRTUAL_ENV`, then `<cwd>/.venv`, `<cwd>/venv`)\n2. Managed venv at `~/.skc/python-env`\n3. `python` or `python3` on PATH\n\nWhen a venv is selected, its bin/Scripts path is prepended to `PATH`.\n\nThe runner additionally receives `PYTHONUNBUFFERED=1` and `PYTHONIOENCODING=utf-8` so streamed output reaches the host promptly.\n\n## Tool availability and mode selection\n\n`eval.py` / `eval.js` (both default `true`) plus optional `SKC_PY` override controls eval backend exposure:\n\n- Python backend only (`eval.py=true`, `eval.js=false`)\n- JavaScript backend only (`eval.py=false`, `eval.js=true`)\n- both backends\n\n`SKC_PY` accepted values:\n\n- `0` / `bash` → JavaScript backend only\n- `1` / `py` → Python backend only\n- `mix` / `both` → both backends\n\nIf Python preflight fails and `eval.js` is enabled, `eval` remains available and dispatches to JavaScript unless `language: \"python\"` is explicitly requested.\n\n## Execution flow and cancellation/timeout\n\n### Tool-level timeout\n\n`eval` timeout is in seconds, default 30, clamped to `1..600`. The tool combines caller abort signal and timeout signal with `AbortSignal.any(...)`.\n\n### Kernel execution cancellation\n\nOn abort/timeout:\n\n- The host sends `kill(\"SIGINT\")` to the runner subprocess.\n- The runner's exec-time signal handler raises `KeyboardInterrupt` inside the user code.\n- Result includes `cancelled=true`; timeout path annotates output as `Command timed out after <n> seconds`.\n- Between requests the runner installs `SIG_IGN` for SIGINT so a stray cancel does not tear down the kernel.\n\nIf a second cancel is required (runner stuck in C code), the host escalates to `SIGTERM` and the session restarts on the next call.\n\n### stdin behavior\n\nInteractive stdin is not supported. The runner does not forward `input()` prompts; user code that calls `input()` blocks until cancellation.\n\n## Output capture and rendering\n\n### Captured output classes\n\nFrom runner frames:\n\n- `stdout` / `stderr` → plain text chunks\n- `display` / `result` → rich display handling (MIME bundle)\n- `error` → traceback text\n- `application/x-skc-status` MIME inside `display` → structured status events\n\nDisplay MIME precedence:\n\n1. `text/markdown`\n2. `text/plain`\n3. `text/html` (converted to basic markdown)\n\nAdditionally captured as structured outputs:\n\n- `application/json` → JSON tree data\n- `image/png` / `image/jpeg` → image payloads\n- `application/x-skc-status` → status events\n\n### Matplotlib\n\nThe runner sets `MPLBACKEND=Agg` as an environ default so figures render off-screen. After every cell, `pyplot.get_fignums()` is iterated; each figure is saved to PNG, emitted as an `image/png` display, and closed.\n\n### Storage and truncation\n\nOutput is streamed through `OutputSink` and may be persisted to artifact storage. Tool results can include truncation metadata and `artifact://<id>` for full output recovery.\n\n### Renderer behavior\n\n- Tool renderer (`eval.ts`):\n - shows code-cell blocks with per-cell status\n - collapsed preview defaults to 10 lines\n - supports expanded mode for full output and richer status detail\n- Interactive renderer (`eval-execution.ts`):\n - used for user-triggered Python execution in TUI\n - collapsed preview defaults to 20 lines\n - clamps very long individual lines to 4000 chars for display safety\n - shows cancellation/error/truncation notices\n\n## Operational troubleshooting\n\n- **Python backend not available** — Check `eval.py`, `SKC_PY`, and that `python`/`python3` is on PATH. If preflight fails and `eval.js` is enabled, omit `language` or pass `language: \"js\"` to use JavaScript.\n- **No Python on PATH** — Install a system Python 3.8+ or place a venv at `~/.skc/python-env`. `skc setup python --check` reports the resolved interpreter.\n- **Execution hangs then times out** — Increase tool `timeout` (max 600s) if workload is legitimate. For stuck native code, cancellation triggers `SIGINT` first then escalates; the session restarts on the next request.\n- **stdin/input prompts in Python code** — `input()` is not supported; pass data programmatically.\n- **Working directory errors** — Tool validates `cwd` exists and is a directory before execution.\n\n## Relevant environment variables\n\n- `SKC_PY` — tool exposure override\n- `SKC_PYTHON_SKIP_CHECK=1` — bypass Python preflight/warm checks\n- `SKC_PYTHON_INTEGRATION=1` — enable gated integration tests that spawn a real Python\n- `SKC_PYTHON_IPC_TRACE=1` — log NDJSON frames exchanged with the runner subprocess\n",
|
|
72
|
-
"readme/README.de.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Programmieren sollte sich wie Denken anfühlen.</strong><br />\n Ein fokussierter Coding-Agent-Runner für Interviews, geprüfte Pläne, tmux-native Ausführung und dauerhafte Verifizierung.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <b>Deutsch</b>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI ist ein experimentelles Projekt im Beta-Stadium. Rechnen Sie mit Ecken und Kanten und überprüfen Sie die Ausgaben, bevor Sie sich bei wichtiger Arbeit darauf verlassen.\n\n## Languages\n\nDie Oberfläche ist in **7 Sprachen** lokalisiert — English, 한국어 (Koreanisch),\n中文 (简体 / Vereinfachtes Chinesisch), 日本語 (Japanisch), Español (Spanisch),\nFrançais (Französisch) und Deutsch. Beim ersten Start erkennt sie automatisch\nIhre System-Locale; wechseln Sie jederzeit unter **Settings → Appearance → Language**\noder starten Sie z. B. mit `LANG=ja_JP.UTF-8 skc`. Nicht übersetzte Zeichenketten\nfallen auf Englisch zurück, und Marken-/Fachbegriffe (Claude, OpenAI, MCP, …)\nbleiben in allen Locales unverändert.\n\n## Was ist Sayknow-CLI?\n\nSayknow-CLI (`skc`) ist ein externes Coding-Agent-Harness. Es läuft aus dem von Ihnen gewählten Repository oder Worktree und gibt dem Agenten dann eine kleine, explizite Workflow-Oberfläche:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nEs ist bewusst kein verstecktes Plugin für Codex CLI, Claude Code, OpenCode oder Claw Code. Starten Sie `skc` neben diesen Tools, wenn Sie strukturierte Planung, dauerhafte Nachweise, tmux-gestützte Worker oder einen isolierten Worktree wünschen.\n\n## Installation\n\n```sh\nnpm install -g sayknow-cli # oder: bun install -g sayknow-cli\nskc --version\n```\n\nDas Paket enthält vorgefertigte native Addons für macOS, Linux und Windows – keine Rust-Toolchain und kein Build-Schritt nötig. Aktualisieren: `npm install -g sayknow-cli@latest` oder `skc update` im Terminal.\n\n> Früher aus dem Quellcode (git clone) installiert? Einmalig umsteigen: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Für die Installation aus dem Quellcode (Entwicklung) siehe die [englische README](../../README.md#install-from-source-development).\n\n## Schnellstart\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nVerwenden Sie innerhalb einer SKC-Sitzung die öffentliche Workflow-Oberfläche:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nFügen Sie `skc team ...` nur hinzu, wenn koordinierte tmux-Worker spürbar helfen.\n\n## Kernfunktionen\n\n- **Interview vor dem Raten**: `deep-interview` verwandelt vage Anfragen in konkrete Anforderungen.\n- **Plan vor der Veränderung**: `ralplan` prüft den Ansatz vor Codeänderungen.\n- **Ausführen mit Nachweisen**: `ultragoal` verfolgt Ziele, Revisionen, Prüfungen und Abschlussnachweise.\n- **Parallelisieren, wenn sinnvoll**: `team` koordiniert tmux-gestützte Worker für größere Aufgaben.\n- **Extern und überprüfbar bleiben**: Laufen Sie aus einem gewählten Repo oder Worktree, ohne eine andere Agent-Runtime zu patchen.\n\n## Workflow-Oberfläche\n\nSayknow-CLI liefert vier Standard-Workflow-Skills:\n\n| Skill | Was es tut |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Klärt mehrdeutige Anforderungen vor Planung oder Codeänderungen. |\n| `ralplan` | Erstellt und kritisiert einen Implementierungsplan vor der Veränderung. |\n| `ultragoal` | Verfolgt Ziele durch Ausführung, Revision, Verifizierung und Nachweise. |\n| `team` | Koordiniert tmux-gestützte Worker, wenn parallele Ausführung sich lohnt. |\n\nUnd vier mitgelieferte Rollen-Agenten:\n\n| Agent | Was es tut |\n| ----------- | -------------------------------------------------- |\n| `executor` | Begrenzte Implementierung, Fixes und Refactorings. |\n| `architect` | Schreibgeschützte Architektur- und Code-Review-Bewertung. |\n| `planner` | Schreibgeschützte Sequenzierung und Abnahmekriterien. |\n| `critic` | Schreibgeschützte Plan-Kritik und Umsetzbarkeitsprüfung. |\n\nKein wucherndes Standard-Skill-Zoo: SKC verbessert sich, indem es diese kleine Methode besser macht.\n\n## Funktioniert neben Ihrem bestehenden Agenten oder Bot\n\n| Tool oder Bot | Empfohlener SKC-Befehl | Grenze |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` oder `skc` | `--worktree` benennt einen SKC-verwalteten Geschwister-Worktree; für einen bestehenden Pfad wechseln Sie zuerst mit `cd` dorthin. |\n| Claude Code | `skc --tmux` oder `skc --tmux --worktree <name>` | SKC wird keine Claude-Code-Erweiterung. |\n| OpenCode | `skc` oder `skc --tmux` | Heute nur External-Runner-Workflow. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC installiert sich nicht in Claw Code und ersetzt es nicht. |\n| Externer Controller / Bot | `skc mcp-serve coordinator` plus `skc setup hermes` für kompatible Konfiguration oder `skc --mode rpc` für einen Subprozess-Worker | Jeder MCP-/RPC-fähige Bot steuert SKC über den generischen Coordinator-/RPC-Vertrag, nicht durch Scrollback-Scraping. |\n\nFür generisches Drittanbieter-Bot-Setup und anbieterunabhängige Smokes siehe [`docs/bot-integration.md`](docs/bot-integration.md). Für die Reife-Klassifizierung über MCP-, RPC-, ACP- und Bridge/HTTPS-Oberflächen siehe [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Für tiefergehende Protokolldetails siehe [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) und [`docs/bridge.md`](docs/bridge.md). Für die Roadmap der Remote-Operator-Oberflächen siehe [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (Web-Steuerrad) und [`docs/telegram-remote.md`](docs/telegram-remote.md) (Telegram-Lifecycle-Button).\n\n## Konfiguration\n\nProvider-Retry-Budgets liegen in `~/.skc/config.yml`:\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries` gilt, bevor ein Stream aufgebaut wird. `streamMaxRetries` gilt nur für replay-sichere, vorübergehende Stream-Fehler. Ungültige Authentifizierung, nicht unterstützte Modelle/Provider, fehlerhafte Requests, Kontextüberlauf, Benutzerabbrüche und dauerhafte Kontingentfehler bleiben fail-fast.\n\n## TUI-Identität\n\nDie Standard-TUI-Identität ist das SKC-**ink-octopus**-Theme — Oktopus-Tinte: warmer Graphit, papierfarbener Text, ein Bernstein-Akzent — für dunkle Terminals, mit **blue-octopus** für helle Terminals. Eine warme **red-octopus**-Variante ist ebenfalls dabei für alle, die eine dunklere, kontrastreiche Palette bevorzugen. Drei zusätzliche Migrations-Themes — `claude-code`, `codex` und `opencode` — spiegeln das Aussehen dieser Tools für einen einfachen Augen-Umstieg wider und sind über Settings oder `/theme` auswählbar. Explizite Benutzer-Theme-Einstellungen gewinnen weiterhin.\n\n### Raster der mitgelieferten Themes\n\nWählen Sie über Settings (`Appearance -> Dark theme` / `Light theme`) oder `/theme`.\n\n| Theme | Visueller Eindruck | Beste Eignung |\n| --- | --- | --- |\n| `blue-octopus` | Blaue Oktopus-Palette mit tentakelblauen Akzenten. | Standard für helle Terminals. |\n| `red-octopus` | Warme rote Oktopus-Variante mit starkem Status-Kontrast. | Kontrastreiche dunkle Alternative. |\n| `ink-octopus` | Oktopus-Tinte — warmer Graphit-Hintergrund, papierfarbener Text, ein einziger Bernstein-Akzent. | Standard für dunkle Terminals. |\n| `glow-octopus` | Tiefsee-Biolumineszenz — Petrol-Schwarz mit leuchtendem Grün und Violett als Zweitfarbe. | Dunkle Terminals mit kräftigem Akzent. |\n| `violet-octopus` | Pflaumendunkel mit Lavendel-Akzenten und Aprikose als Zweitfarbe. | Weiche, farbige dunkle Alternative. |\n| `claude-code` | Von Claude Code inspirierte dunkle Palette mit terrakotta- und pinkfarbenen Highlights. | Claude-Code-Muskelgedächtnis, ohne SKC zu verlassen. |\n| `codex` | Klare dunkle blaugraue Palette mit schärferem Coding-Session-Kontrast. | Ein Codex-ähnlicher dunkler Arbeitsbereich. |\n| `opencode` | Von OpenCode inspirierte dunkle Palette mit kräftigeren Terminal-Akzenten. | OpenCode-Muskelgedächtnis im mitgelieferten Picker. |\n\n## Entwicklung\n\nAbhängigkeiten installieren, native Bindings bauen und lokale Standardwerte einrichten:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nDie `.node`-Binärdatei für `@sayknow-cli/natives` ist gitignored und vor jeder CLI-Ausführung erforderlich (`install:defaults`, `dev:link`, Tests).\n\n### Kanonisch: Entwickler-`skc` bauen und verlinken\n\nDamit der globale Befehl `skc` **den TypeScript-Quellcode dieses Checkouts** ausführt (live bei jeder Bearbeitung, mit funktionierenden Skills/Natives), verlinken Sie ihn in Ihren `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` legt einen Symlink `skc` → `packages/coding-agent/src/cli.ts` nach `~/.local/bin` an (überschreibbar mit `SKC_DEV_LINK_DIR`), ersetzt dieses verwaltete Ziel, warnt und schlägt fehl, falls ein anderes `skc` es weiter vorne im `PATH` überschattet, und führt `--smoke-test` aus, um zu bestätigen, dass `@sayknow-cli/natives` geladen wird. Verwenden Sie `bun run install:dev` für das vollständige Bootstrap (Installation + Link + `setup defaults`).\n\nPrüfen Sie jederzeit, ob Ihr `skc` abgedriftet ist (falsche Quelle oder eine kompilierte Binärdatei, die keine Skills laden kann):\n\n```sh\nbun run dev:doctor\n```\n\n> Verwenden Sie für die tägliche Entwicklung **nicht** die kompilierte Binärdatei. `bun --cwd=packages/coding-agent run build` erzeugt ein eigenständiges `dist/skc`, aber eine mit `bun build --compile` erstellte Binärdatei kann `@sayknow-cli/natives` nicht dynamisch laden, sodass Skills mit `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` fehlschlagen. Die Ausführung aus dem Quellcode über `dev:link` vermeidet dies. Bauen Sie die Binärdatei nur, wenn Sie ein Release validieren.\n\nFühren Sie die CLI direkt aus dem Quellcode ohne Verlinkung aus:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nStandard-Workflow-Definitionen liegen im Quellcode, nicht in committeten `.skc`-Kopien:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nFür Änderungen an Workflow-Definitionen oder Rebrand-Oberflächen führen Sie die Projekt-Gates aus:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nFür eine Paket-für-Paket-Übersicht siehe [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Mitwirkende\n\nBeiträge, Fehlerberichte und Release-Validierung sind über GitHub Issues und Pull Requests willkommen.\n\n## Inspirationen und Herkunft\n\nDie Standard-TUI-Identität von Sayknow-CLI ist die Oktopus-Familie: ink-octopus als dunkler Standard, blue-octopus als heller Standard sowie red-octopus, glow-octopus und violet-octopus als Alternativen. Es liefert außerdem die Migrations-Themes `claude-code`, `codex` und `opencode`, deren Paletten von diesen Tools inspiriert sind, damit Benutzer, die von ihnen wechseln, einen vertrauten Look erhalten. Es baut auf Erkenntnissen aus einer kleinen Familie von Agent-Harnesses auf und hält die öffentliche SKC-Oberfläche bewusst fokussiert. Die historische Zuordnung wird in [`NOTICE.md`](NOTICE.md) geführt.\n\n## Lizenz\n\nMIT. Siehe [`LICENSE`](LICENSE).\n",
|
|
73
|
-
"readme/README.es.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Ilustración principal del agente de codificación autónomo Sayknow-CLI\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Programar debería sentirse como pensar.</strong><br />\n Un ejecutor de agentes de codificación enfocado en entrevistas, planes revisados, ejecución nativa en tmux y verificación duradera.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <b>Español</b> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Mascota personaje de Sayknow-CLI\" width=\"320\" />\n</p>\n\n> Sayknow-CLI es un proyecto experimental en fase beta. Espera asperezas y verifica los resultados antes de confiar en él para trabajos importantes.\n\n## Languages\n\nLa interfaz está localizada en **7 idiomas** — English, 한국어 (coreano),\n中文 (简体 / chino simplificado), 日本語 (japonés), Español,\nFrançais (francés) y Deutsch (alemán). Detecta automáticamente la configuración regional de tu sistema en\nel primer arranque; cámbiala en cualquier momento en **Settings → Appearance → Language**, o inícialo\ncon, por ejemplo, `LANG=ja_JP.UTF-8 skc`. Las cadenas no traducidas recurren al inglés, y\nlos nombres de marca/técnicos (Claude, OpenAI, MCP, …) se mantienen literales en todas las configuraciones regionales.\n\n## ¿Qué es Sayknow-CLI?\n\nSayknow-CLI (`skc`) es un arnés externo de agentes de codificación. Se ejecuta desde el repositorio o worktree que elijas y luego le da al agente una superficie de flujo de trabajo pequeña y explícita:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nIntencionadamente no es un plugin oculto para Codex CLI, Claude Code, OpenCode o Claw Code. Inicia `skc` junto a esas herramientas cuando quieras planificación estructurada, evidencia persistente, workers respaldados por tmux o un worktree aislado.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # o: bun install -g sayknow-cli\nskc --version\n```\n\nEl paquete incluye binarios nativos precompilados para macOS, Linux y Windows, así que no necesitas Rust ni paso de compilación. Para actualizar: `npm install -g sayknow-cli@latest` o ejecuta `skc update` en la terminal.\n\n> ¿Vienes de una instalación desde el código fuente (git clone)? Cambia una sola vez: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Para la instalación desde el código (desarrollo), consulta el [README en inglés](../../README.md#install-from-source-development).\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nDentro de una sesión de SKC, usa la superficie pública del flujo de trabajo:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nAñade `skc team ...` solo cuando los workers coordinados de tmux ayuden de forma significativa.\n\n## Capacidades principales\n\n- **Entrevistar antes de suponer**: `deep-interview` convierte solicitudes vagas en requisitos concretos.\n- **Planificar antes de mutar**: `ralplan` revisa el enfoque antes de los cambios de código.\n- **Ejecutar con evidencia**: `ultragoal` rastrea objetivos, revisiones, comprobaciones y evidencia de finalización.\n- **Paralelizar cuando sea útil**: `team` coordina workers respaldados por tmux para tareas más grandes.\n- **Mantenerse externo y revisable**: ejecútalo desde un repositorio o worktree elegido sin parchear otro runtime de agente.\n\n## Superficie del flujo de trabajo\n\nSayknow-CLI incluye cuatro skills de flujo de trabajo predeterminadas:\n\n| Skill | Qué hace |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Aclara requisitos ambiguos antes de planificar o cambiar código. |\n| `ralplan` | Construye y critica un plan de implementación antes de mutar. |\n| `ultragoal` | Rastrea objetivos a través de ejecución, revisión, verificación y evidencia. |\n| `team` | Coordina workers respaldados por tmux cuando vale la pena la ejecución paralela. |\n\nY cuatro agentes de rol incluidos:\n\n| Agent | Qué hace |\n| ----------- | -------------------------------------------------- |\n| `executor` | Implementación acotada, correcciones y refactorizaciones. |\n| `architect` | Evaluación de arquitectura y revisión de código de solo lectura. |\n| `planner` | Secuenciación y criterios de aceptación de solo lectura. |\n| `critic` | Crítica de planes y revisión de accionabilidad de solo lectura. |\n\nSin un zoológico de skills predeterminadas desbordante: SKC mejora haciendo mejor este pequeño método.\n\n## Funciona junto a tu agente o bot existente\n\n| Herramienta o bot | Comando SKC recomendado | Límite |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` o `skc` | `--worktree` nombra un worktree hermano gestionado por SKC; para una ruta existente, haz `cd` allí primero. |\n| Claude Code | `skc --tmux` o `skc --tmux --worktree <name>` | SKC no se convierte en una extensión de Claude Code. |\n| OpenCode | `skc` o `skc --tmux` | Solo flujo de trabajo de ejecutor externo por ahora. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC no se instala dentro de Claw Code ni lo reemplaza. |\n| Controlador / bot externo | `skc mcp-serve coordinator` más `skc setup hermes` para una configuración compatible, o `skc --mode rpc` para un worker en subproceso | Cualquier bot con capacidad MCP/RPC controla SKC mediante el contrato genérico coordinator/RPC, no mediante scraping del scrollback. |\n\nPara la configuración genérica de bots de terceros y pruebas de humo independientes del proveedor, consulta [`docs/bot-integration.md`](docs/bot-integration.md). Para la clasificación de preparación a través de las superficies MCP, RPC, ACP y Bridge/HTTPS, consulta [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Para los detalles de protocolo de más bajo nivel, consulta [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) y [`docs/bridge.md`](docs/bridge.md). Para la hoja de ruta de las superficies de operador remoto, consulta [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (volante web) y [`docs/telegram-remote.md`](docs/telegram-remote.md) (botón de ciclo de vida de Telegram).\n\n## Configuration\n\nLos presupuestos de reintento del proveedor viven en `~/.skc/config.yml`:\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries` se aplica antes de que se establezca un stream. `streamMaxRetries` se aplica solo a fallos transitorios de stream que son seguros de reproducir. La autenticación inválida, los modelos/proveedores no compatibles, las solicitudes malformadas, el desbordamiento de contexto, las cancelaciones del usuario y los fallos permanentes de cuota siguen siendo de fallo rápido.\n\n## Identidad de la TUI\n\nLa identidad predeterminada de la TUI es el tema **ink-octopus** de SKC — tinta de pulpo: grafito cálido, texto color papel y un único acento ámbar — para terminales oscuras, con **blue-octopus** para terminales claras. También se incluye una variante cálida **red-octopus** para quienes prefieren una paleta más oscura y de alto contraste. Tres temas de migración adicionales — `claude-code`, `codex` y `opencode` — reflejan el aspecto de esas herramientas para facilitar la migración visual y se pueden seleccionar desde Settings o `/theme`. Los ajustes de tema explícitos del usuario siguen prevaleciendo.\n\n### Cuadrícula de temas incluidos\n\nElige desde Settings (`Appearance -> Dark theme` / `Light theme`) o `/theme`.\n\n| Tema | Sensación visual | Mejor uso |\n| --- | --- | --- |\n| `blue-octopus` | Paleta de pulpo azul con acentos azul-tentáculo. | Predeterminado para terminales claras. |\n| `red-octopus` | Variante cálida de pulpo rojo con fuerte contraste de estado. | Alternativa oscura de alto contraste. |\n| `ink-octopus` | Tinta de pulpo — fondo grafito cálido, texto color papel y un único acento ámbar. | Predeterminado para terminales oscuras. |\n| `glow-octopus` | Bioluminiscencia abisal — negro verdiazulado con verde brillante y violeta como secundario. | Terminales oscuras que quieren un acento vivo. |\n| `violet-octopus` | Oscuro ciruela con acentos lavanda y albaricoque como secundario. | Alternativa oscura suave y colorida. |\n| `claude-code` | Paleta oscura inspirada en Claude Code con resaltados terracota y rosa. | Memoria muscular de Claude Code sin salir de SKC. |\n| `codex` | Paleta nítida azul-gris oscuro con un contraste de sesión de codificación más marcado. | Un espacio de trabajo oscuro al estilo Codex. |\n| `opencode` | Paleta oscura inspirada en OpenCode con acentos de terminal más vibrantes. | Memoria muscular de OpenCode en el selector incluido. |\n\n## Development\n\nInstala las dependencias, compila los bindings nativos y configura los valores predeterminados locales:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nEl binario `.node` para `@sayknow-cli/natives` está en gitignore y es necesario antes de cualquier invocación del CLI (`install:defaults`, `dev:link`, tests).\n\n### Canónico: compilar y enlazar el `skc` de desarrollo\n\nPara hacer que el comando global `skc` ejecute **el código fuente TypeScript de esta copia** (sensible a cada edición, con skills/natives funcionando), enlázalo a tu `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` crea un symlink de `skc` → `packages/coding-agent/src/cli.ts` en `~/.local/bin` (sobrescríbelo con `SKC_DEV_LINK_DIR`), reemplaza ese objetivo gestionado, advierte y falla si otro `skc` aún lo oculta antes en `PATH`, y ejecuta `--smoke-test` para confirmar que `@sayknow-cli/natives` carga. Usa `bun run install:dev` para el bootstrap completo (install + link + `setup defaults`).\n\nComprueba en cualquier momento si tu `skc` se ha desviado (fuente incorrecta, o un binario compilado que no puede cargar skills):\n\n```sh\nbun run dev:doctor\n```\n\n> **No** uses el binario compilado para el desarrollo diario. `bun --cwd=packages/coding-agent run build` produce un `dist/skc` independiente, pero un binario `bun build --compile` no puede cargar dinámicamente `@sayknow-cli/natives`, por lo que las skills fallan con `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`. Ejecutar desde el código fuente mediante `dev:link` evita esto. Compila el binario solo al validar una release.\n\nEjecuta el CLI directamente desde el código fuente sin enlazarlo:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nLas definiciones de flujo de trabajo predeterminadas viven en el código fuente, no en copias `.skc` comprometidas:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nPara cambios en las definiciones de flujo de trabajo o en la superficie de rebranding, ejecuta las puertas del proyecto:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nPara un mapa paquete por paquete, consulta [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Contributors\n\nLas contribuciones, los informes de errores y la validación de releases son bienvenidos a través de GitHub Issues y Pull Requests.\n\n## Inspiraciones y linaje\n\nLa identidad predeterminada de la TUI de Sayknow-CLI es la familia de pulpos: ink-octopus como predeterminado oscuro, blue-octopus como predeterminado claro y red-octopus, glow-octopus y violet-octopus como alternativas. También incluye los temas de migración `claude-code`, `codex` y `opencode`, cuyas paletas están inspiradas en esas herramientas para que los usuarios que migran de ellas obtengan un aspecto familiar. Se basa en las lecciones de una pequeña familia de arneses de agentes mientras mantiene la superficie pública de SKC intencionadamente enfocada. La atribución histórica se conserva en [`NOTICE.md`](NOTICE.md).\n\n## License\n\nMIT. Consulta [`LICENSE`](LICENSE).\n",
|
|
74
|
-
"readme/README.fr.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Illustration héros de l'agent de codage autonome Sayknow-CLI\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Coder devrait ressembler à réfléchir.</strong><br />\n Un exécuteur d'agent de codage ciblé pour les entretiens, les plans révisés, l'exécution native tmux et la vérification durable.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <b>Français</b> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Mascotte personnage de Sayknow-CLI\" width=\"320\" />\n</p>\n\n> Sayknow-CLI est un projet expérimental en phase bêta. Attendez-vous à des aspérités et vérifiez les résultats avant de vous y fier pour un travail important.\n\n## Languages\n\nL'interface est localisée en **7 langues** — English, 한국어 (coréen),\n中文 (简体 / chinois simplifié), 日本語 (japonais), Español (espagnol),\nFrançais (français) et Deutsch (allemand). Elle détecte automatiquement la locale de votre système au\npremier lancement ; changez-en à tout moment dans **Settings → Appearance → Language**, ou lancez\navec par exemple `LANG=ja_JP.UTF-8 skc`. Les chaînes non traduites se rabattent sur l'anglais, et\nles noms de marque/techniques (Claude, OpenAI, MCP, …) restent verbatim dans toutes les locales.\n\n## What is Sayknow-CLI?\n\nSayknow-CLI (`skc`) est un harnais d'agent de codage externe. Il s'exécute depuis le dépôt ou le worktree que vous choisissez, puis donne à l'agent une surface de workflow réduite et explicite :\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nCe n'est volontairement pas un plugin caché pour Codex CLI, Claude Code, OpenCode ou Claw Code. Lancez `skc` à côté de ces outils lorsque vous voulez une planification structurée, des preuves persistantes, des workers adossés à tmux, ou un worktree isolé.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # ou : bun install -g sayknow-cli\nskc --version\n```\n\nLe paquet embarque des binaires natifs précompilés pour macOS, Linux et Windows : aucune chaîne d'outils Rust ni étape de compilation. Pour mettre à jour : `npm install -g sayknow-cli@latest` ou lancez `skc update` dans le terminal.\n\n> Vous veniez d'une installation depuis les sources (git clone) ? Basculez une seule fois : `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Pour l'installation depuis les sources (développement), voir le [README en anglais](../../README.md#install-from-source-development).\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nÀ l'intérieur d'une session SKC, utilisez la surface de workflow publique :\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nAjoutez `skc team ...` uniquement lorsque des workers tmux coordonnés aident concrètement.\n\n## Core capabilities\n\n- **Interviewer avant de deviner** : `deep-interview` transforme des demandes vagues en exigences concrètes.\n- **Planifier avant de muter** : `ralplan` révise l'approche avant les changements de code.\n- **Exécuter avec des preuves** : `ultragoal` suit les objectifs, les révisions, les vérifications et les preuves de complétion.\n- **Paralléliser quand c'est utile** : `team` coordonne des workers adossés à tmux pour les tâches plus importantes.\n- **Rester externe et révisable** : exécutez depuis un dépôt ou un worktree choisi sans patcher un autre runtime d'agent.\n\n## Workflow surface\n\nSayknow-CLI fournit quatre skills de workflow par défaut :\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Clarifie les exigences ambiguës avant la planification ou les changements de code. |\n| `ralplan` | Construit et critique un plan d'implémentation avant la mutation. |\n| `ultragoal` | Suit les objectifs à travers l'exécution, la révision, la vérification et les preuves. |\n| `team` | Coordonne des workers adossés à tmux lorsque l'exécution parallèle en vaut la peine. |\n\nEt quatre agents de rôle inclus :\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | Implémentation bornée, correctifs et refactorisations. |\n| `architect` | Évaluation d'architecture et de revue de code en lecture seule. |\n| `planner` | Séquençage et critères d'acceptation en lecture seule. |\n| `critic` | Critique de plan et revue d'actionnabilité en lecture seule. |\n\nPas de ménagerie tentaculaire de skills par défaut : SKC s'améliore en rendant cette petite méthode meilleure.\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` nomme un worktree frère géré par SKC ; pour un chemin existant, faites d'abord `cd` à cet endroit. |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC ne devient pas une extension de Claude Code. |\n| OpenCode | `skc` or `skc --tmux` | Workflow d'exécuteur externe uniquement aujourd'hui. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC ne s'installe pas dans Claw Code et ne le remplace pas. |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | Tout bot capable de MCP/RPC pilote SKC via le contrat générique coordinator/RPC, et non par grattage de scrollback. |\n\nPour la configuration générique d'un bot tiers et les smokes indépendants du provider, voir [`docs/bot-integration.md`](docs/bot-integration.md). Pour la classification de readiness à travers les surfaces MCP, RPC, ACP et Bridge/HTTPS, voir [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Pour les détails de protocole de plus bas niveau, voir [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) et [`docs/bridge.md`](docs/bridge.md). Pour la roadmap des surfaces d'opérateur distant, voir [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (volant de direction web) et [`docs/telegram-remote.md`](docs/telegram-remote.md) (bouton de cycle de vie Telegram).\n\n## Configuration\n\nLes budgets de retry du provider se trouvent dans `~/.skc/config.yml` :\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries` s'applique avant qu'un stream ne soit établi. `streamMaxRetries` ne s'applique qu'aux échecs de stream transitoires sûrs pour le replay. L'authentification invalide, les modèles/providers non pris en charge, les requêtes malformées, le débordement de contexte, les abandons par l'utilisateur et les échecs de quota permanents restent en fail-fast.\n\n## TUI identity\n\nL'identité TUI par défaut est le thème SKC **ink-octopus** — encre de poulpe : graphite chaud, texte couleur papier, un seul accent ambre — pour les terminaux sombres, avec **blue-octopus** pour les terminaux clairs. Une variante chaleureuse **red-octopus** est également incluse pour ceux qui préfèrent une palette plus sombre et à fort contraste. Trois thèmes de migration supplémentaires — `claude-code`, `codex` et `opencode` — reflètent l'apparence de ces outils pour faciliter la migration visuelle et sont sélectionnables depuis Settings ou `/theme`. Les réglages de thème explicites de l'utilisateur l'emportent toujours.\n\n### Bundled theme grid\n\nChoisissez depuis Settings (`Appearance -> Dark theme` / `Light theme`) ou `/theme`.\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | Palette poulpe bleu avec des accents bleu tentacule. | Par défaut pour les terminaux clairs. |\n| `red-octopus` | Variante chaleureuse poulpe rouge avec un fort contraste d'état. | Alternative sombre à fort contraste. |\n| `ink-octopus` | Encre de poulpe — fond graphite chaud, texte couleur papier, un seul accent ambre. | Par défaut pour les terminaux sombres. |\n| `glow-octopus` | Bioluminescence abyssale — noir sarcelle avec un vert lumineux et un violet secondaire. | Terminaux sombres qui veulent un accent vif. |\n| `violet-octopus` | Sombre prune avec des accents lavande et un abricot secondaire. | Alternative sombre douce et colorée. |\n| `claude-code` | Palette sombre inspirée de Claude Code avec des touches terracotta et rose. | La mémoire musculaire de Claude Code sans quitter SKC. |\n| `codex` | Palette bleu-gris sombre et nette avec un contraste de session de codage plus marqué. | Un espace de travail sombre à la manière de Codex. |\n| `opencode` | Palette sombre inspirée d'OpenCode avec des accents de terminal plus percutants. | La mémoire musculaire d'OpenCode dans le sélecteur inclus. |\n\n## Development\n\nInstallez les dépendances, compilez les bindings natifs et configurez les valeurs par défaut locales :\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nLe binaire `.node` pour `@sayknow-cli/natives` est gitignored et requis avant toute invocation de la CLI (`install:defaults`, `dev:link`, tests).\n\n### Canonical: build and link the dev `skc`\n\nPour que la commande globale `skc` exécute **la source TypeScript de ce checkout** (sensible à chaque édition, avec skills/natives fonctionnels), liez-la à votre `PATH` :\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` crée un lien symbolique `skc` → `packages/coding-agent/src/cli.ts` dans `~/.local/bin` (à surcharger avec `SKC_DEV_LINK_DIR`), remplace cette cible gérée, avertit et échoue si un autre `skc` le masque encore plus tôt sur le `PATH`, et exécute `--smoke-test` pour confirmer que `@sayknow-cli/natives` se charge. Utilisez `bun run install:dev` pour le bootstrap complet (install + link + `setup defaults`).\n\nVérifiez à tout moment si votre `skc` a dérivé (mauvaise source, ou un binaire compilé qui ne peut pas charger les skills) :\n\n```sh\nbun run dev:doctor\n```\n\n> N'utilisez **pas** le binaire compilé pour le développement quotidien. `bun --cwd=packages/coding-agent run build` produit un `dist/skc` autonome, mais un binaire `bun build --compile` ne peut pas charger dynamiquement `@sayknow-cli/natives`, donc les skills échouent avec `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`. L'exécution depuis la source via `dev:link` évite cela. Ne compilez le binaire que lors de la validation d'une release.\n\nExécutez la CLI depuis la source directement sans lier :\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nLes définitions de workflow par défaut résident dans la source, et non dans des copies `.skc` commitées :\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nPour les changements de définition de workflow ou de surface de rebrand, exécutez les portes du projet :\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nPour une carte package par package, voir [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Contributors\n\nLes contributions, les rapports de bugs et la validation de release sont les bienvenus via les GitHub Issues et les Pull Requests.\n\n## Inspirations and lineage\n\nL'identité TUI par défaut de Sayknow-CLI est la famille de poulpes : ink-octopus par défaut en sombre, blue-octopus par défaut en clair, et red-octopus, glow-octopus et violet-octopus en alternatives. Il inclut aussi les thèmes de migration `claude-code`, `codex` et `opencode` dont les palettes sont inspirées de ces outils afin que les utilisateurs qui en proviennent retrouvent une apparence familière. Il s'appuie sur les leçons d'une petite famille de harnais d'agents tout en gardant la surface publique SKC volontairement ciblée. L'attribution historique est conservée dans [`NOTICE.md`](NOTICE.md).\n\n## License\n\nMIT. Voir [`LICENSE`](LICENSE).\n",
|
|
75
|
-
"readme/README.ja.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI 自律型コーディングエージェントのヒーローイラスト\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>コーディングは、考えることのように感じられるべきだ。</strong><br />\n インタビュー、レビュー済みプラン、tmux ネイティブ実行、そして永続的な検証のための、集中型コーディングエージェントランナー。\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <b>日本語</b> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI キャラクターマスコット\" width=\"320\" />\n</p>\n\n> Sayknow-CLI は実験的なベータ段階のプロジェクトです。粗削りな部分があることを想定し、重要な作業で頼る前には出力を検証してください。\n\n## Languages\n\nインターフェースは **7 言語** にローカライズされています — English、한국어 (韓国語)、\n中文 (简体 / 簡体字中国語)、日本語 (Japanese)、Español (スペイン語)、\nFrançais (フランス語)、そして Deutsch (ドイツ語)。初回起動時にシステムロケールを\n自動検出します。**Settings → Appearance → Language** でいつでも切り替えられるほか、\nたとえば `LANG=ja_JP.UTF-8 skc` のように起動することもできます。未翻訳の文字列は英語に\nフォールバックし、ブランド名や技術名 (Claude、OpenAI、MCP、…) はすべてのロケールで\nそのまま表示されます。\n\n## Sayknow-CLI とは?\n\nSayknow-CLI (`skc`) は外部コーディングエージェントのハーネスです。選択したリポジトリまたは worktree から実行され、エージェントに対して小さく明示的なワークフロー面を提供します:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nこれは意図的に、Codex CLI、Claude Code、OpenCode、Claw Code 向けの隠しプラグインにはなっていません。構造化されたプランニング、永続的なエビデンス、tmux ベースのワーカー、または分離された worktree が欲しいときに、それらのツールと並べて `skc` を起動してください。\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # または: bun install -g sayknow-cli\nskc --version\n```\n\nmacOS・Linux・Windows 向けのビルド済みネイティブを同梱しているため、Rust ツールチェーンやビルド手順は不要です。更新は `npm install -g sayknow-cli@latest`、またはターミナルで `skc update`。\n\n> 以前ソース(git clone)からインストールした場合は、一度だけ `rm -f ~/.local/bin/skc && npm install -g sayknow-cli` で切り替えてください。ソース/開発インストールは[英語版 README](../../README.md#install-from-source-development)を参照。\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nSKC セッション内では、公開されているワークフロー面を使用してください:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n`skc team ...` は、協調する tmux ワーカーが実質的に役立つときにのみ追加してください。\n\n## Core capabilities\n\n- **推測する前にインタビューする**: `deep-interview` は曖昧なリクエストを具体的な要件に変えます。\n- **変更する前にプランニングする**: `ralplan` はコード変更の前にアプローチをレビューします。\n- **エビデンスとともに実行する**: `ultragoal` はゴール、リビジョン、チェック、完了エビデンスを追跡します。\n- **役立つときに並列化する**: `team` はより大きなタスクのために tmux ベースのワーカーを協調させます。\n- **外部かつレビュー可能であり続ける**: 別のエージェントランタイムにパッチを当てることなく、選択したリポジトリまたは worktree から実行します。\n\n## Workflow surface\n\nSayknow-CLI は 4 つのデフォルトワークフロースキルを同梱しています:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | プランニングやコード変更の前に、曖昧な要件を明確化します。 |\n| `ralplan` | 変更の前に実装プランを構築し批評します。 |\n| `ultragoal` | 実行、リビジョン、検証、エビデンスを通じてゴールを追跡します。 |\n| `team` | 並列実行に価値があるときに tmux ベースのワーカーを協調させます。 |\n\nそして 4 つの同梱ロールエージェント:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 範囲を限定した実装、修正、リファクタリング。 |\n| `architect` | 読み取り専用のアーキテクチャおよびコードレビュー評価。 |\n| `planner` | 読み取り専用のシーケンシングと受け入れ基準。 |\n| `critic` | 読み取り専用のプラン批評と実行可能性レビュー。 |\n\n肥大化したデフォルトスキルの動物園はありません: SKC はこの小さなメソッドをより良くすることで改善されます。\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` は SKC が管理する兄弟 worktree に名前を付けます。既存のパスを使う場合は、まずそこへ `cd` してください。 |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC は Claude Code の拡張機能にはなりません。 |\n| OpenCode | `skc` or `skc --tmux` | 現時点では外部ランナーのワークフローのみです。 |\n| Claw Code | `skc --tmux --worktree <name>` | SKC は Claw Code にインストールされたり、置き換えたりはしません。 |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | MCP/RPC 対応のボットはどれも、スクロールバックのスクレイピングではなく、汎用のコーディネーター/RPC コントラクトを通じて SKC を駆動します。 |\n\n汎用的なサードパーティボットのセットアップとプロバイダー非依存のスモークテストについては、[`docs/bot-integration.md`](docs/bot-integration.md) を参照してください。MCP、RPC、ACP、Bridge/HTTPS 各面にわたる準備状況の分類については、[`docs/external-control-readiness.md`](docs/external-control-readiness.md) を参照してください。より低レベルのプロトコル詳細については、[`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md)、[`docs/rpc.md`](docs/rpc.md)、および [`docs/bridge.md`](docs/bridge.md) を参照してください。リモートオペレーター面のロードマップについては、[`docs/sayknow-remote.md`](docs/sayknow-remote.md) (web steering wheel) と [`docs/telegram-remote.md`](docs/telegram-remote.md) (Telegram lifecycle button) を参照してください。\n\n## Configuration\n\nプロバイダーのリトライバジェットは `~/.skc/config.yml` にあります:\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries` はストリームが確立される前に適用されます。`streamMaxRetries` はリプレイ安全な一時的ストリーム障害にのみ適用されます。無効な認証、サポートされていないモデル/プロバイダー、不正な形式のリクエスト、コンテキストオーバーフロー、ユーザーによる中断、および恒久的なクォータ障害は、引き続きフェイルファストのままです。\n\n## TUI identity\n\nデフォルトの TUI アイデンティティは SKC の **ink-octopus** テーマ — タコの墨: 温かみのあるグラファイト、紙色の文字、琥珀色のアクセント 1 色 — でダークターミナルに適用され、ライトターミナルには **blue-octopus** が適用されます。より暗めでハイコントラストなパレットを好む人のために、温かみのある **red-octopus** バリアントも同梱されています。さらに 3 つの移行用テーマ — `claude-code`、`codex`、`opencode` — がそれらのツールの見た目を再現しており、視覚的な移行を容易にし、Settings または `/theme` から選択できます。ユーザーが明示的に設定したテーマは引き続き優先されます。\n\n### Bundled theme grid\n\nSettings (`Appearance -> Dark theme` / `Light theme`) または `/theme` から選択してください。\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | テンタクルブルーのアクセントを持つ青いタコのパレット。 | ライトターミナルのデフォルト。 |\n| `red-octopus` | 強いステータスコントラストを持つ温かみのある赤いタコのバリアント。 | ハイコントラストなダークの代替。 |\n| `ink-octopus` | タコの墨 — 温かみのあるグラファイト背景、紙色の文字、琥珀色のアクセント 1 色。 | ダークターミナルのデフォルト。 |\n| `glow-octopus` | 深海の生物発光 — ティールがかった黒に発光グリーン、サブにバイオレット。 | 鮮やかなアクセントが欲しいダークターミナル。 |\n| `violet-octopus` | プラム色のダークにラベンダーのアクセント、サブにアプリコット。 | 柔らかくカラフルなダークの代替。 |\n| `claude-code` | テラコッタとピンクのハイライトを持つ Claude Code 風のダークパレット。 | SKC を離れずに Claude Code の体に染み付いた操作感を。 |\n| `codex` | よりシャープなコーディングセッションのコントラストを持つ、くっきりしたダークブルーグレーのパレット。 | Codex ライクなダークワークスペース。 |\n| `opencode` | よりパンチの効いたターミナルアクセントを持つ OpenCode 風のダークパレット。 | 同梱のピッカーで OpenCode の体に染み付いた操作感を。 |\n\n## Development\n\n依存関係をインストールし、ネイティブバインディングをビルドし、ローカルのデフォルトをセットアップします:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives` 用の `.node` バイナリは gitignore されており、あらゆる CLI 呼び出し (`install:defaults`、`dev:link`、テスト) の前に必要です。\n\n### Canonical: build and link the dev `skc`\n\nグローバルの `skc` コマンドが **このチェックアウトの TypeScript ソース** を実行するようにする (すべての編集に即座に反映され、スキル/ネイティブが動作する) には、それをあなたの `PATH` にリンクします:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` は `skc` → `packages/coding-agent/src/cli.ts` を `~/.local/bin` にシンボリックリンクし (`SKC_DEV_LINK_DIR` で上書き可能)、その管理対象ターゲットを置き換え、別の `skc` が `PATH` 上でより前にそれをシャドウしている場合は警告して失敗し、`--smoke-test` を実行して `@sayknow-cli/natives` がロードされることを確認します。完全なブートストラップ (install + link + `setup defaults`) には `bun run install:dev` を使用してください。\n\nあなたの `skc` がドリフトしていないか (誤ったソース、またはスキルをロードできないコンパイル済みバイナリ) は、いつでも確認できます:\n\n```sh\nbun run dev:doctor\n```\n\n> 日常の開発にコンパイル済みバイナリを **使わないでください**。`bun --cwd=packages/coding-agent run build` はスタンドアロンの `dist/skc` を生成しますが、`bun build --compile` のバイナリは `@sayknow-cli/natives` を動的にロードできないため、スキルは `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` で失敗します。`dev:link` を通じてソースから実行すれば、これを回避できます。バイナリのビルドはリリースを検証するときのみ行ってください。\n\nリンクせずに CLI をソースから直接実行します:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nデフォルトのワークフロー定義はソースにあり、コミットされた `.skc` のコピーにはありません:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nワークフロー定義またはリブランド面の変更については、プロジェクトのゲートを実行してください:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nパッケージごとのマップについては、[`docs/codebase-overview.md`](docs/codebase-overview.md) を参照してください。\n\n## Contributors\n\nコントリビューション、バグレポート、リリース検証は GitHub の Issues と Pull Request を通じて歓迎しています。\n\n## Inspirations and lineage\n\nSayknow-CLI のデフォルト TUI アイデンティティはタコのファミリーです: ダークのデフォルト ink-octopus、ライトのデフォルト blue-octopus、そして red-octopus・glow-octopus・violet-octopus の代替。また、`claude-code`、`codex`、`opencode` の移行用テーマも同梱しており、これらのパレットはそれらのツールにインスパイアされているため、移行してくるユーザーが見慣れた見た目を得られます。これは、公開された SKC 面を意図的に集中させたまま、小さなエージェントハーネス一族からの教訓の上に構築されています。歴史的な帰属表示は [`NOTICE.md`](NOTICE.md) に保持されています。\n\n## License\n\nMIT。[`LICENSE`](LICENSE) を参照してください。\n",
|
|
76
|
-
"readme/README.ko.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>코딩은 사고처럼 느껴져야 합니다.</strong><br />\n 인터뷰, 검토된 계획, tmux 네이티브 실행, 견고한 검증을 위한 집중형 코딩 에이전트 러너.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <b>한국어</b> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI는 실험적인 베타 단계 프로젝트입니다. 거친 부분이 있을 수 있으니 중요한 작업에 의존하기 전에 출력 결과를 검증하세요.\n\n## Languages\n\n인터페이스는 **7개 언어** — English, 한국어 (Korean),\n中文 (简体 / Simplified Chinese), 日本語 (Japanese), Español (Spanish),\nFrançais (French), Deutsch (German) — 로 현지화되어 있습니다. 첫 실행 시\n시스템 로케일을 자동으로 감지하며, 언제든지 **Settings → Appearance → Language** 에서\n전환하거나 예를 들어 `LANG=ja_JP.UTF-8 skc` 로 실행할 수 있습니다. 번역되지 않은 문자열은\nEnglish로 대체되며, 브랜드/기술 이름(Claude, OpenAI, MCP, …)은 모든 로케일에서 그대로 유지됩니다.\n\n## What is Sayknow-CLI?\n\nSayknow-CLI(`skc`)는 외부 코딩 에이전트 하니스입니다. 선택한 저장소나 워크트리에서 실행되며, 에이전트에게 작고 명시적인 워크플로 표면을 제공합니다:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\n이것은 의도적으로 Codex CLI, Claude Code, OpenCode, Claw Code의 숨겨진 플러그인이 아닙니다. 구조화된 계획, 지속적인 증거, tmux 기반 워커, 또는 격리된 워크트리를 원할 때 이러한 도구들 옆에서 `skc`를 시작하세요.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # 또는: bun install -g sayknow-cli\nskc --version\n```\n\n프리빌드 네이티브(macOS·Linux·Windows)가 포함돼 있어 Rust 툴체인이나 빌드가 필요 없습니다. 업데이트는 `npm install -g sayknow-cli@latest` 또는 터미널에서 `skc update`.\n\n> 이전에 소스(git clone)로 설치했다면 한 번만 `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`로 전환하세요. 소스/개발 설치는 [영문 README](../../README.md#install-from-source-development) 참고.\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nSKC 세션 내부에서는, 공개 워크플로 표면을 사용하세요:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n조율된 tmux 워커가 실질적으로 도움이 될 때만 `skc team ...`을 추가하세요.\n\n## Core capabilities\n\n- **추측하기 전에 인터뷰**: `deep-interview`는 모호한 요청을 구체적인 요구사항으로 바꿉니다.\n- **변경하기 전에 계획**: `ralplan`은 코드 변경 전에 접근 방식을 검토합니다.\n- **증거와 함께 실행**: `ultragoal`은 목표, 수정, 점검, 완료 증거를 추적합니다.\n- **유용할 때 병렬화**: `team`은 더 큰 작업을 위해 tmux 기반 워커를 조율합니다.\n- **외부에서 검토 가능하게 유지**: 다른 에이전트 런타임을 패치하지 않고 선택한 저장소나 워크트리에서 실행합니다.\n\n## Workflow surface\n\nSayknow-CLI는 네 가지 기본 워크플로 스킬을 제공합니다:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | 계획이나 코드 변경 전에 모호한 요구사항을 명확히 합니다. |\n| `ralplan` | 변경 전에 구현 계획을 구축하고 비평합니다. |\n| `ultragoal` | 실행, 수정, 검증, 증거를 거쳐 목표를 추적합니다. |\n| `team` | 병렬 실행이 가치가 있을 때 tmux 기반 워커를 조율합니다. |\n\n그리고 네 가지 번들 역할 에이전트:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 범위가 정해진 구현, 수정, 리팩터. |\n| `architect` | 읽기 전용 아키텍처 및 코드 리뷰 평가. |\n| `planner` | 읽기 전용 순서 결정 및 수용 기준. |\n| `critic` | 읽기 전용 계획 비평 및 실행 가능성 검토. |\n\n광범위한 기본 스킬 동물원은 없습니다: SKC는 이 작은 방법을 더 좋게 만들어 개선됩니다.\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree`는 SKC가 관리하는 형제 워크트리의 이름을 지정합니다. 기존 경로의 경우 먼저 그곳으로 `cd` 하세요. |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC는 Claude Code 확장이 되지 않습니다. |\n| OpenCode | `skc` or `skc --tmux` | 현재로서는 외부 러너 워크플로만 지원합니다. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC는 Claw Code에 설치되거나 그것을 대체하지 않습니다. |\n| External controller / bot | 호환 가능한 구성을 위한 `skc mcp-serve coordinator` 및 `skc setup hermes`, 또는 서브프로세스 워커를 위한 `skc --mode rpc` | MCP/RPC 지원 봇이라면 무엇이든 스크롤백 스크래핑이 아니라 일반 coordinator/RPC 계약을 통해 SKC를 구동합니다. |\n\n일반 서드파티 봇 설정 및 공급자 독립적 스모크에 대해서는 [`docs/bot-integration.md`](docs/bot-integration.md)를 참조하세요. MCP, RPC, ACP, Bridge/HTTPS 표면 전반의 준비도 분류에 대해서는 [`docs/external-control-readiness.md`](docs/external-control-readiness.md)를 참조하세요. 더 낮은 수준의 프로토콜 세부 사항에 대해서는 [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md), [`docs/bridge.md`](docs/bridge.md)를 참조하세요. 원격 운영자 표면 로드맵에 대해서는 [`docs/sayknow-remote.md`](docs/sayknow-remote.md)(웹 스티어링 휠) 및 [`docs/telegram-remote.md`](docs/telegram-remote.md)(Telegram 라이프사이클 버튼)를 참조하세요.\n\n## Configuration\n\n공급자 재시도 예산은 `~/.skc/config.yml`에 있습니다:\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries`는 스트림이 설정되기 전에 적용됩니다. `streamMaxRetries`는 재생 안전한 일시적 스트림 실패에만 적용됩니다. 잘못된 인증, 지원되지 않는 모델/공급자, 잘못된 형식의 요청, 컨텍스트 오버플로, 사용자 중단, 영구적인 할당량 실패는 즉시 실패(fail-fast)로 유지됩니다.\n\n## TUI identity\n\n기본 TUI 정체성은 SKC **ink-octopus** 테마 — 문어 먹물: 따뜻한 흑연색, 종이색 글자, 호박색 강조 하나 — 로 다크 터미널에 적용되며, 라이트 터미널에는 **blue-octopus**가 적용됩니다. 더 어둡고 고대비 팔레트를 선호하는 사람들을 위해 따뜻한 **red-octopus** 변형도 번들로 제공됩니다. 세 가지 추가 마이그레이션 테마 — `claude-code`, `codex`, `opencode` — 는 쉬운 눈 마이그레이션을 위해 해당 도구들의 모습을 그대로 따르며 Settings 또는 `/theme`에서 선택할 수 있습니다. 명시적인 사용자 테마 설정이 여전히 우선합니다.\n\n### Bundled theme grid\n\nSettings (`Appearance -> Dark theme` / `Light theme`) 또는 `/theme`에서 선택하세요.\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | 촉수 블루 액센트가 있는 파란 문어 팔레트. | 라이트 터미널의 기본값. |\n| `red-octopus` | 강한 상태 대비를 가진 따뜻한 빨간 문어 변형. | 고대비 다크 대안. |\n| `ink-octopus` | 문어 먹물 — 따뜻한 흑연색 배경, 종이색 글자, 호박색 강조 하나. | 다크 터미널의 기본값. |\n| `glow-octopus` | 심해 생물발광 — 틸빛 어둠에 발광 초록, 보조로 보라. | 선명한 강조색을 원하는 다크 터미널. |\n| `violet-octopus` | 자줏빛 어둠에 라벤더 강조, 보조로 살구색. | 부드럽고 화사한 다크 대안. |\n| `claude-code` | 테라코타와 핑크 하이라이트가 있는 Claude Code 영감 다크 팔레트. | SKC를 떠나지 않고 Claude Code 근육 기억을 유지. |\n| `codex` | 더 날카로운 코딩 세션 대비를 가진 선명한 다크 블루그레이 팔레트. | Codex 같은 다크 작업 공간. |\n| `opencode` | 더 강렬한 터미널 액센트를 가진 OpenCode 영감 다크 팔레트. | 번들 선택기에서의 OpenCode 근육 기억. |\n\n## Development\n\n의존성을 설치하고, 네이티브 바인딩을 빌드하고, 로컬 기본값을 설정하세요:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives`용 `.node` 바이너리는 gitignore되어 있으며 모든 CLI 호출(`install:defaults`, `dev:link`, 테스트) 전에 필요합니다.\n\n### Canonical: build and link the dev `skc`\n\n전역 `skc` 명령이 **이 체크아웃의 TypeScript 소스**(모든 편집에 즉시 반영되며, 스킬/네이티브가 작동함)를 실행하도록 하려면, `PATH`에 링크하세요:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link`는 `skc` → `packages/coding-agent/src/cli.ts`를 `~/.local/bin`에 심볼릭 링크하고(`SKC_DEV_LINK_DIR`로 재정의 가능), 그 관리되는 대상을 교체하며, 다른 `skc`가 여전히 `PATH`에서 더 앞쪽에 있어 그것을 가린다면 경고하고 실패하며, `--smoke-test`를 실행하여 `@sayknow-cli/natives`가 로드되는지 확인합니다. 전체 부트스트랩(install + link + `setup defaults`)을 위해서는 `bun run install:dev`를 사용하세요.\n\n당신의 `skc`가 표류했는지(잘못된 소스, 또는 스킬을 로드할 수 없는 컴파일된 바이너리) 언제든지 확인하세요:\n\n```sh\nbun run dev:doctor\n```\n\n> 일상적인 개발에는 컴파일된 바이너리를 **사용하지 마세요**. `bun --cwd=packages/coding-agent run build`는 독립 실행형 `dist/skc`를 생성하지만, `bun build --compile` 바이너리는 `@sayknow-cli/natives`를 동적으로 로드할 수 없으므로 스킬이 `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`로 실패합니다. `dev:link`를 통해 소스에서 실행하면 이를 피할 수 있습니다. 릴리스를 검증할 때만 바이너리를 빌드하세요.\n\n링크 없이 소스에서 직접 CLI를 실행하세요:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\n기본 워크플로 정의는 커밋된 `.skc` 사본이 아니라 소스에 있습니다:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\n워크플로 정의 또는 리브랜드 표면 변경의 경우, 프로젝트 게이트를 실행하세요:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\n패키지별 맵에 대해서는 [`docs/codebase-overview.md`](docs/codebase-overview.md)를 참조하세요.\n\n## Contributors\n\n기여, 버그 보고, 릴리스 검증은 GitHub Issues와 Pull Request를 통해 환영합니다.\n\n## Inspirations and lineage\n\nSayknow-CLI의 기본 TUI 정체성은 문어 가족입니다: 다크 기본값 ink-octopus, 라이트 기본값 blue-octopus, 그리고 red-octopus·glow-octopus·violet-octopus 대안. 또한 해당 도구들에서 옮겨오는 사용자들이 익숙한 모습을 얻도록 팔레트가 그 도구들에서 영감을 받은 `claude-code`, `codex`, `opencode` 마이그레이션 테마를 번들로 제공합니다. 공개 SKC 표면을 의도적으로 집중된 상태로 유지하면서, 작은 에이전트 하니스 계열에서 얻은 교훈을 바탕으로 만들어졌습니다. 역사적 출처 표기는 [`NOTICE.md`](NOTICE.md)에 보관되어 있습니다.\n\n## License\n\nMIT. [`LICENSE`](LICENSE)를 참조하세요.\n",
|
|
77
|
-
"readme/README.zh.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>编码应当如思考般自然。</strong><br />\n 一个专注的编码智能体运行器,面向访谈式需求澄清、经评审的计划、tmux 原生执行与持久化验证。\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <b>中文</b> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI 是一个实验性的、处于 beta 阶段的项目。请预期会有粗糙之处,并在依赖其结果完成重要工作之前先行验证输出。\n\n## Languages\n\n界面已本地化为 **7 种语言**——English、한국어(韩语)、\n中文(简体)、日本語(日语)、Español(西班牙语)、\nFrançais(法语)以及 Deutsch(德语)。首次运行时它会自动检测你的系统区域设置;\n你可以随时在 **Settings → Appearance → Language** 中切换,或者使用例如\n`LANG=ja_JP.UTF-8 skc` 的方式启动。未翻译的字符串会回退到英文,而\n品牌/技术名称(Claude、OpenAI、MCP……)在所有语言环境中均保持原样。\n\n## What is Sayknow-CLI?\n\nSayknow-CLI(`skc`)是一个外部编码智能体框架(harness)。它从你选择的仓库或工作树(worktree)中运行,然后为智能体提供一个精简、明确的工作流界面:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\n它有意不做成 Codex CLI、Claude Code、OpenCode 或 Claw Code 的隐藏插件。当你需要结构化的规划、持久化的证据、tmux 支持的工作进程或一个隔离的工作树时,就在这些工具旁边启动 `skc`。\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # 或:bun install -g sayknow-cli\nskc --version\n```\n\n已内置 macOS·Linux·Windows 的预编译原生模块,无需 Rust 工具链或构建步骤。更新:`npm install -g sayknow-cli@latest` 或在终端运行 `skc update`。\n\n> 如果你之前是从源码(git clone)安装的,只需一次性切换:`rm -f ~/.local/bin/skc && npm install -g sayknow-cli`。源码/开发安装请参见[英文 README](../../README.md#install-from-source-development)。\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\n在 SKC 会话内部,使用公共工作流界面:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n仅当协同的 tmux 工作进程能带来实质性帮助时,才加上 `skc team ...`。\n\n## Core capabilities\n\n- **先访谈,不靠猜**:`deep-interview` 把模糊的请求转化为具体的需求。\n- **先规划,再变更**:`ralplan` 在代码改动之前评审方案。\n- **带证据地执行**:`ultragoal` 跟踪目标、修订、检查以及完成证据。\n- **在有用时并行化**:`team` 为较大的任务协调 tmux 支持的工作进程。\n- **保持外部化且可评审**:从所选的仓库或工作树中运行,无需给另一个智能体运行时打补丁。\n\n## Workflow surface\n\nSayknow-CLI 内置四项默认工作流技能:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | 在规划或代码改动之前澄清模糊的需求。 |\n| `ralplan` | 在变更之前构建并评审实现计划。 |\n| `ultragoal` | 在执行、修订、验证与证据收集的全过程中跟踪目标。 |\n| `team` | 当并行执行值得时,协调 tmux 支持的工作进程。 |\n\n以及四个捆绑的角色智能体:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 有边界的实现、修复与重构。 |\n| `architect` | 只读的架构与代码评审评估。 |\n| `planner` | 只读的排序与验收标准。 |\n| `critic` | 只读的计划评审与可执行性审查。 |\n\n没有庞杂的默认技能堆砌:SKC 通过把这一精简方法做得更好来持续改进。\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` 指定一个由 SKC 管理的同级工作树;对于已存在的路径,请先 `cd` 到那里。 |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC 不会成为 Claude Code 的扩展。 |\n| OpenCode | `skc` or `skc --tmux` | 目前仅支持外部运行器(external-runner)工作流。 |\n| Claw Code | `skc --tmux --worktree <name>` | SKC 不会安装到 Claw Code 中,也不会替代它。 |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | 任何具备 MCP/RPC 能力的 bot 都通过通用的 coordinator/RPC 契约来驱动 SKC,而非抓取滚动回显(scrollback scraping)。 |\n\n关于通用第三方 bot 的设置以及与提供商无关的冒烟测试,请参阅 [`docs/bot-integration.md`](docs/bot-integration.md)。关于在 MCP、RPC、ACP 与 Bridge/HTTPS 各界面上的就绪度分级,请参阅 [`docs/external-control-readiness.md`](docs/external-control-readiness.md)。关于更底层的协议细节,请参阅 [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md)、[`docs/rpc.md`](docs/rpc.md) 以及 [`docs/bridge.md`](docs/bridge.md)。关于远程操作员界面的路线图,请参阅 [`docs/sayknow-remote.md`](docs/sayknow-remote.md)(网页方向盘)以及 [`docs/telegram-remote.md`](docs/telegram-remote.md)(Telegram 生命周期按钮)。\n\n## Configuration\n\n提供商重试预算位于 `~/.skc/config.yml`:\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n```\n\n`requestMaxRetries` 在流(stream)建立之前生效。`streamMaxRetries` 仅适用于可安全重放的瞬时流失败。无效的认证、不受支持的模型/提供商、格式错误的请求、上下文溢出、用户中止以及永久性配额失败仍然保持快速失败(fail-fast)。\n\n## TUI identity\n\n默认的 TUI 标识是 SKC 的 **ink-octopus**(章鱼墨汁)主题——温暖的石墨色、纸色文字、唯一的琥珀色强调——用于深色终端,浅色终端使用 **blue-octopus**(蓝章鱼)。还捆绑了一个暖色调的 **red-octopus**(红章鱼)变体,供偏好更深、高对比度配色的用户使用。另有三个迁移主题——`claude-code`、`codex` 和 `opencode`——分别复刻了这些工具的外观,以便于视觉迁移,可从 Settings 或 `/theme` 中选择。显式的用户主题设置仍然优先生效。\n\n### Bundled theme grid\n\n从 Settings(`Appearance -> Dark theme` / `Light theme`)或 `/theme` 中选择。\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | 蓝章鱼配色,带触手蓝点缀。 | 浅色终端的默认主题。 |\n| `red-octopus` | 暖色调红章鱼变体,状态对比强烈。 | 高对比度的深色替代方案。 |\n| `ink-octopus` | 章鱼墨汁 — 温暖的石墨色背景、纸色文字、唯一的琥珀色强调。 | 深色终端的默认主题。 |\n| `glow-octopus` | 深海生物荧光 — 青黑底色配荧光绿,辅以紫色。 | 需要鲜明强调色的深色终端。 |\n| `violet-octopus` | 梅紫色深色底配薰衣草强调,辅以杏色。 | 柔和多彩的深色备选。 |\n| `claude-code` | 受 Claude Code 启发的深色配色,带赤陶色和粉色高光。 | 在不离开 SKC 的情况下保留 Claude Code 的肌肉记忆。 |\n| `codex` | 清爽的深蓝灰配色,编码会话对比更锐利。 | 类似 Codex 的深色工作区。 |\n| `opencode` | 受 OpenCode 启发的深色配色,终端点缀更鲜明。 | 在捆绑选择器中保留 OpenCode 的肌肉记忆。 |\n\n## Development\n\n安装依赖、构建原生绑定,并设置本地默认值:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives` 的 `.node` 二进制文件已被 gitignore,且在任何 CLI 调用(`install:defaults`、`dev:link`、测试)之前都是必需的。\n\n### Canonical: build and link the dev `skc`\n\n要让全局 `skc` 命令运行**此检出的 TypeScript 源码**(对每一次编辑都即时生效,且技能/原生绑定均可用),请把它链接到你的 `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` 会把 `skc` → `packages/coding-agent/src/cli.ts` 软链接到 `~/.local/bin`(可用 `SKC_DEV_LINK_DIR` 覆盖),替换该受管目标,如果另一个 `skc` 仍在 `PATH` 上更靠前地遮蔽它则会发出警告并失败,并运行 `--smoke-test` 以确认 `@sayknow-cli/natives` 能够加载。使用 `bun run install:dev` 进行完整的引导(install + link + `setup defaults`)。\n\n随时检查你的 `skc` 是否已经漂移(源码错误,或一个无法加载技能的已编译二进制文件):\n\n```sh\nbun run dev:doctor\n```\n\n> 在日常开发中**不要**使用已编译的二进制文件。`bun --cwd=packages/coding-agent run build` 会产出一个独立的 `dist/skc`,但 `bun build --compile` 生成的二进制无法动态加载 `@sayknow-cli/natives`,因此技能会以 `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` 失败。通过 `dev:link` 从源码运行可避免此问题。仅在验证发布版本时才构建该二进制文件。\n\n不进行链接,直接从源码运行 CLI:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\n默认工作流定义存放在源码中,而非已提交的 `.skc` 副本:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\n对于工作流定义或品牌重塑界面(rebrand-surface)的改动,请运行项目门禁(gates):\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\n关于逐包(package-by-package)的对照图,请参阅 [`docs/codebase-overview.md`](docs/codebase-overview.md)。\n\n## Contributors\n\n欢迎通过 GitHub Issues 和 Pull Requests 进行贡献、提交错误报告以及参与发布验证。\n\n## Inspirations and lineage\n\nSayknow-CLI 默认的 TUI 标识是章鱼家族:深色默认 ink-octopus,浅色默认 blue-octopus,以及 red-octopus、glow-octopus、violet-octopus 备选。它还捆绑了 `claude-code`、`codex` 和 `opencode` 迁移主题,其配色受这些工具启发,以便从它们迁移过来的用户能获得熟悉的外观。它在一个小型智能体框架家族的经验之上构建,同时有意保持公共 SKC 界面的专注。历史归属保留在 [`NOTICE.md`](NOTICE.md) 中。\n\n## License\n\nMIT。参见 [`LICENSE`](LICENSE)。\n",
|
|
73
|
+
"readme/README.de.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Programmieren sollte sich wie Denken anfühlen.</strong><br />\n Ein fokussierter Coding-Agent-Runner für Interviews, geprüfte Pläne, tmux-native Ausführung und dauerhafte Verifizierung.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <b>Deutsch</b>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI ist ein experimentelles Projekt im Beta-Stadium. Rechnen Sie mit Ecken und Kanten und überprüfen Sie die Ausgaben, bevor Sie sich bei wichtiger Arbeit darauf verlassen.\n\n## Languages\n\nDie Oberfläche ist in **7 Sprachen** lokalisiert — English, 한국어 (Koreanisch),\n中文 (简体 / Vereinfachtes Chinesisch), 日本語 (Japanisch), Español (Spanisch),\nFrançais (Französisch) und Deutsch. Beim ersten Start erkennt sie automatisch\nIhre System-Locale; wechseln Sie jederzeit unter **Settings → Appearance → Language**\noder starten Sie z. B. mit `LANG=ja_JP.UTF-8 skc`. Nicht übersetzte Zeichenketten\nfallen auf Englisch zurück, und Marken-/Fachbegriffe (Claude, OpenAI, MCP, …)\nbleiben in allen Locales unverändert.\n\n## Was ist Sayknow-CLI?\n\nSayknow-CLI (`skc`) ist ein externes Coding-Agent-Harness. Es läuft aus dem von Ihnen gewählten Repository oder Worktree und gibt dem Agenten dann eine kleine, explizite Workflow-Oberfläche:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nEs ist bewusst kein verstecktes Plugin für Codex CLI, Claude Code, OpenCode oder Claw Code. Starten Sie `skc` neben diesen Tools, wenn Sie strukturierte Planung, dauerhafte Nachweise, tmux-gestützte Worker oder einen isolierten Worktree wünschen.\n\n## Installation\n\n```sh\nnpm install -g sayknow-cli # oder: bun install -g sayknow-cli\nskc --version\n```\n\nDas Paket enthält vorgefertigte native Addons für macOS, Linux und Windows – keine Rust-Toolchain und kein Build-Schritt nötig. Aktualisieren: `npm install -g sayknow-cli@latest` oder `skc update` im Terminal.\n\n> Früher aus dem Quellcode (git clone) installiert? Einmalig umsteigen: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Für die Installation aus dem Quellcode (Entwicklung) siehe die [englische README](../../README.md#install-from-source-development).\n\n## Schnellstart\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nVerwenden Sie innerhalb einer SKC-Sitzung die öffentliche Workflow-Oberfläche:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nFügen Sie `skc team ...` nur hinzu, wenn koordinierte tmux-Worker spürbar helfen.\n\n## Kernfunktionen\n\n- **Interview vor dem Raten**: `deep-interview` verwandelt vage Anfragen in konkrete Anforderungen.\n- **Plan vor der Veränderung**: `ralplan` prüft den Ansatz vor Codeänderungen.\n- **Ausführen mit Nachweisen**: `ultragoal` verfolgt Ziele, Revisionen, Prüfungen und Abschlussnachweise.\n- **Parallelisieren, wenn sinnvoll**: `team` koordiniert tmux-gestützte Worker für größere Aufgaben.\n- **Extern und überprüfbar bleiben**: Laufen Sie aus einem gewählten Repo oder Worktree, ohne eine andere Agent-Runtime zu patchen.\n- **Weiterarbeiten, wenn ein Provider ausfällt**: Ist das Standardmodell blockiert (keine Zugangsdaten, Kontingent erschöpft, Auth- oder Serverfehler), läuft die Sitzung mit einem Modell eines anderen Providers weiter; `/fallback` zeigt und bearbeitet diese Kette. Ein Schritt, der durch einen Neustart oder einen vorübergehenden Fehler unterbrochen wurde, wird einmal von selbst auf demselben Modell fortgesetzt. Bei Kontingentantworten wie Z.AI `1113` geht es nach einer einzigen Anfrage weiter, statt das Retry-Budget aufzubrauchen.\n- **Lange Sitzungen bleiben im Kontextfenster**: Nach einer Kompaktierung startet Codex von einer frischen, für den Provider sichtbaren Basis, statt auf `context_length_exceeded` zuzuwachsen, und Kompaktierungs-Zusammenfassungen sind so formuliert, dass Provider sie nicht ablehnen.\n- **Code nach Bedeutung finden**: Das Tool `locate` findet anhand einer einfachen Beschreibung, wo ein Verhalten implementiert ist, wenn Sie keinen Namen zum Greppen haben.\n- **Arbeit an das richtige Modell leiten**: `/model` weist Modelle pro Rolle und pro Einsatzzweck im Detail zu; Subagent-Aufgaben deklarieren eine `specialty`, damit sie auf dem Modell landen, das Sie für diese Art von Arbeit gewählt haben.\n- **Direkt aus der Sitzung ausliefern**: Die Tools `github` und `gitlab` öffnen und prüfen Pull-/Merge-Requests und CI, ohne SKC zu verlassen.\n- **Belegen, dass die Tests auf diesem Code liefen**: Das Plugin `verification-receipts` speichert zu jedem Testlauf einen Beleg und meldet, wenn sich der Code seitdem geändert hat.\n- **Zu jeder Sitzung zurückkehren**: `alt+r` öffnet die Fortsetzen-Auswahl, `ctrl+q` setzt die letzte Sitzung fort, dazu `/star`, `/fork`, `/rename` und `/import-session` für Codex- und Claude-Code-Transkripte.\n\n## Workflow-Oberfläche\n\nSayknow-CLI liefert vier Standard-Workflow-Skills:\n\n| Skill | Was es tut |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Klärt mehrdeutige Anforderungen vor Planung oder Codeänderungen. |\n| `ralplan` | Erstellt und kritisiert einen Implementierungsplan vor der Veränderung. |\n| `ultragoal` | Verfolgt Ziele durch Ausführung, Revision, Verifizierung und Nachweise. |\n| `team` | Koordiniert tmux-gestützte Worker, wenn parallele Ausführung sich lohnt. |\n\nUnd vier mitgelieferte Rollen-Agenten:\n\n| Agent | Was es tut |\n| ----------- | -------------------------------------------------- |\n| `executor` | Begrenzte Implementierung, Fixes und Refactorings. |\n| `architect` | Schreibgeschützte Architektur- und Code-Review-Bewertung. |\n| `planner` | Schreibgeschützte Sequenzierung und Abnahmekriterien. |\n| `critic` | Schreibgeschützte Plan-Kritik und Umsetzbarkeitsprüfung. |\n\nKein wucherndes Standard-Skill-Zoo: SKC verbessert sich, indem es diese kleine Methode besser macht.\n\n## Integrierte Tools\n\nDer Agent arbeitet mit diesen Tools. Als *opt-in* markierte Tools bleiben deaktiviert, bis Sie sie unter **Settings → Tools** (oder über den angegebenen Schlüssel in `~/.skc/config.yml`) aktivieren.\n\n| Bereich | Tools |\n| ---- | ----- |\n| Dateien und Code | `read`, `write`, `edit`, `find`, `search`, `locate` (Code per Beschreibung finden), `ast_grep` / `ast_edit` (syntaxbewusstes Suchen und Umschreiben), `lsp` |\n| Shell und Laufzeit | `bash`, `eval` (JS-/Python-Zellen), `ssh`, `debug`, `bisect`, `calc` |\n| Delegation und Tracking | `task` (Subagents), `subagent`, `job`, `monitor`, `cron`, `irc` (mit laufenden Agenten sprechen), `todo_write`, `goal`, `checkpoint` / `rewind` |\n| Git-Hosting | `github` (*opt-in*, `github.enabled`): Pull Requests, Pushes, CI-Läufe über `gh` · `gitlab` (*opt-in*, `gitlab.enabled`, benötigt [`glab`](https://gitlab.com/gitlab-org/cli)): `mr_create` (liefert den bereits offenen MR statt eines Duplikats), `mr_view`, `mr_list`, `ci_status` für gitlab.com und selbst gehostete Instanzen |\n| Web und Geräte | `web_search`, `browser`, `computer`, `render_mermaid` |\n| Discovery | `search_tool_bm25` (aktiviert versteckte und MCP-Tools bei Bedarf), `skill`, `skill_discovery`, `ask` |\n\nMit `--tools read,bash,...` wählen Sie das Tool-Set für einen einzelnen Lauf; auch Plugin-, benutzerdefinierte und MCP-Toolnamen werden dort akzeptiert.\n\n## Plugins\n\nSKC lädt Plugin-Bundles (Tools, Hooks, Skills, MCP-Server), deren Hashes bei der Installation geprüft werden und die in Quarantäne kommen, wenn sich danach eine Datei ändert. Verwaltet werden sie mit `skc plugin install|list|...`.\n\n**`verification-receipts`** (in diesem Repository enthalten) beantwortet die Frage „Haben die Tests auf dem Code, der jetzt da ist, tatsächlich bestanden?“:\n\n- `verification_run` führt explizit angegebene Testdateien mit `bun test` oder `node --test` aus und speichert einen unveränderlichen Beleg: Bestanden-/Fehlgeschlagen-Zahlen pro Datei plus einen Fingerabdruck des Arbeitsverzeichnisses.\n- `verification_status` berechnet diesen Fingerabdruck neu, ohne die Tests erneut auszuführen, und meldet `fresh` oder, sobald sich der Code geändert hat, `stale`.\n- `verification_loop` und seine Hooks erinnern Sie, wenn ein `task` im Hintergrund ohne aktuellen Beleg beendet wurde.\n\nEs dient nur als Hinweis, läuft nur unter POSIX und benötigt Node 24.11.1+ für `node --test`. Es ist nicht Teil des npm-Pakets; installieren Sie es aus einem Checkout:\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Funktioniert neben Ihrem bestehenden Agenten oder Bot\n\n| Tool oder Bot | Empfohlener SKC-Befehl | Grenze |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` oder `skc` | `--worktree` benennt einen SKC-verwalteten Geschwister-Worktree; für einen bestehenden Pfad wechseln Sie zuerst mit `cd` dorthin. |\n| Claude Code | `skc --tmux` oder `skc --tmux --worktree <name>` | SKC wird keine Claude-Code-Erweiterung. |\n| OpenCode | `skc` oder `skc --tmux` | Heute nur External-Runner-Workflow. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC installiert sich nicht in Claw Code und ersetzt es nicht. |\n| Externer Controller / Bot | `skc mcp-serve coordinator` plus `skc setup hermes` für kompatible Konfiguration oder `skc --mode rpc` für einen Subprozess-Worker | Jeder MCP-/RPC-fähige Bot steuert SKC über den generischen Coordinator-/RPC-Vertrag, nicht durch Scrollback-Scraping. |\n\nFür generisches Drittanbieter-Bot-Setup und anbieterunabhängige Smokes siehe [`docs/bot-integration.md`](docs/bot-integration.md). Für die Reife-Klassifizierung über MCP-, RPC-, ACP- und Bridge/HTTPS-Oberflächen siehe [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Für tiefergehende Protokolldetails siehe [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) und [`docs/bridge.md`](docs/bridge.md). Für die Roadmap der Remote-Operator-Oberflächen siehe [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (Web-Steuerrad) und [`docs/telegram-remote.md`](docs/telegram-remote.md) (Telegram-Lifecycle-Button).\n\n## Konfiguration\n\nRetry-, Resume- und Fallback-Verhalten der Provider liegt in `~/.skc/config.yml` (die Werte unten sind die Standardwerte):\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # einen unterbrochenen Schritt einmal fortsetzen, auf demselben Modell\n maxSilentTimeouts: 3 # nach so vielen Timeouts ohne Ausgabe abbrechen\nfallback:\n auto: true # bei blockiertem Standardmodell mit einem anderen angemeldeten Provider weitermachen\n maxAttempts: 3 # Versuche pro Modell der Kette, bevor zum nächsten gewechselt wird\n```\n\n`requestMaxRetries` gilt, bevor ein Stream aufgebaut wird. `streamMaxRetries` gilt nur für replay-sichere, vorübergehende Stream-Fehler. Ungültige Authentifizierung, nicht unterstützte Modelle/Provider, fehlerhafte Requests, Kontextüberlauf, Benutzerabbrüche und dauerhafte Kontingentfehler schlagen auf dem aktuellen Modell sofort fehl; mit `fallback.auto` übergibt ein blockiertes Standardmodell dann an das nächste Modell der Kette (`/fallback` zeigt und bearbeitet sie).\n\n## TUI-Identität\n\nDie Standard-TUI-Identität ist das SKC-**ink-octopus**-Theme — Oktopus-Tinte: warmer Graphit, papierfarbener Text, ein Bernstein-Akzent — für dunkle Terminals, mit **blue-octopus** für helle Terminals. Eine warme **red-octopus**-Variante ist ebenfalls dabei für alle, die eine dunklere, kontrastreiche Palette bevorzugen. Drei zusätzliche Migrations-Themes — `claude-code`, `codex` und `opencode` — spiegeln das Aussehen dieser Tools für einen einfachen Augen-Umstieg wider und sind über Settings oder `/theme` auswählbar. Explizite Benutzer-Theme-Einstellungen gewinnen weiterhin.\n\n### Raster der mitgelieferten Themes\n\nWählen Sie über Settings (`Appearance -> Dark theme` / `Light theme`) oder `/theme`.\n\n| Theme | Visueller Eindruck | Beste Eignung |\n| --- | --- | --- |\n| `blue-octopus` | Blaue Oktopus-Palette mit tentakelblauen Akzenten. | Standard für helle Terminals. |\n| `red-octopus` | Warme rote Oktopus-Variante mit starkem Status-Kontrast. | Kontrastreiche dunkle Alternative. |\n| `ink-octopus` | Oktopus-Tinte — warmer Graphit-Hintergrund, papierfarbener Text, ein einziger Bernstein-Akzent. | Standard für dunkle Terminals. |\n| `glow-octopus` | Tiefsee-Biolumineszenz — Petrol-Schwarz mit leuchtendem Grün und Violett als Zweitfarbe. | Dunkle Terminals mit kräftigem Akzent. |\n| `violet-octopus` | Pflaumendunkel mit Lavendel-Akzenten und Aprikose als Zweitfarbe. | Weiche, farbige dunkle Alternative. |\n| `claude-code` | Von Claude Code inspirierte dunkle Palette mit terrakotta- und pinkfarbenen Highlights. | Claude-Code-Muskelgedächtnis, ohne SKC zu verlassen. |\n| `codex` | Klare dunkle blaugraue Palette mit schärferem Coding-Session-Kontrast. | Ein Codex-ähnlicher dunkler Arbeitsbereich. |\n| `opencode` | Von OpenCode inspirierte dunkle Palette mit kräftigeren Terminal-Akzenten. | OpenCode-Muskelgedächtnis im mitgelieferten Picker. |\n\n## Entwicklung\n\nAbhängigkeiten installieren, native Bindings bauen und lokale Standardwerte einrichten:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nDie `.node`-Binärdatei für `@sayknow-cli/natives` ist gitignored und vor jeder CLI-Ausführung erforderlich (`install:defaults`, `dev:link`, Tests).\n\n### Kanonisch: Entwickler-`skc` bauen und verlinken\n\nDamit der globale Befehl `skc` **den TypeScript-Quellcode dieses Checkouts** ausführt (live bei jeder Bearbeitung, mit funktionierenden Skills/Natives), verlinken Sie ihn in Ihren `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` legt einen Symlink `skc` → `packages/coding-agent/src/cli.ts` nach `~/.local/bin` an (überschreibbar mit `SKC_DEV_LINK_DIR`), ersetzt dieses verwaltete Ziel, warnt und schlägt fehl, falls ein anderes `skc` es weiter vorne im `PATH` überschattet, und führt `--smoke-test` aus, um zu bestätigen, dass `@sayknow-cli/natives` geladen wird. Verwenden Sie `bun run install:dev` für das vollständige Bootstrap (Installation + Link + `setup defaults`).\n\nPrüfen Sie jederzeit, ob Ihr `skc` abgedriftet ist (falsche Quelle oder eine kompilierte Binärdatei, die keine Skills laden kann):\n\n```sh\nbun run dev:doctor\n```\n\n> Verwenden Sie für die tägliche Entwicklung **nicht** die kompilierte Binärdatei. `bun --cwd=packages/coding-agent run build` erzeugt ein eigenständiges `dist/skc`, aber eine mit `bun build --compile` erstellte Binärdatei kann `@sayknow-cli/natives` nicht dynamisch laden, sodass Skills mit `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` fehlschlagen. Die Ausführung aus dem Quellcode über `dev:link` vermeidet dies. Bauen Sie die Binärdatei nur, wenn Sie ein Release validieren.\n\nFühren Sie die CLI direkt aus dem Quellcode ohne Verlinkung aus:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nStandard-Workflow-Definitionen liegen im Quellcode, nicht in committeten `.skc`-Kopien:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nFür Änderungen an Workflow-Definitionen oder Rebrand-Oberflächen führen Sie die Projekt-Gates aus:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nFür eine Paket-für-Paket-Übersicht siehe [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Mitwirkende\n\nBeiträge, Fehlerberichte und Release-Validierung sind über GitHub Issues und Pull Requests willkommen.\n\n## Inspirationen und Herkunft\n\nDie Standard-TUI-Identität von Sayknow-CLI ist die Oktopus-Familie: ink-octopus als dunkler Standard, blue-octopus als heller Standard sowie red-octopus, glow-octopus und violet-octopus als Alternativen. Es liefert außerdem die Migrations-Themes `claude-code`, `codex` und `opencode`, deren Paletten von diesen Tools inspiriert sind, damit Benutzer, die von ihnen wechseln, einen vertrauten Look erhalten. Es baut auf Erkenntnissen aus einer kleinen Familie von Agent-Harnesses auf und hält die öffentliche SKC-Oberfläche bewusst fokussiert. Die historische Zuordnung wird in [`NOTICE.md`](NOTICE.md) geführt.\n\n## Lizenz\n\nMIT. Siehe [`LICENSE`](LICENSE).\n",
|
|
74
|
+
"readme/README.es.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Ilustración principal del agente de codificación autónomo Sayknow-CLI\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Programar debería sentirse como pensar.</strong><br />\n Un ejecutor de agentes de codificación enfocado en entrevistas, planes revisados, ejecución nativa en tmux y verificación duradera.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <b>Español</b> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Mascota personaje de Sayknow-CLI\" width=\"320\" />\n</p>\n\n> Sayknow-CLI es un proyecto experimental en fase beta. Espera asperezas y verifica los resultados antes de confiar en él para trabajos importantes.\n\n## Languages\n\nLa interfaz está localizada en **7 idiomas** — English, 한국어 (coreano),\n中文 (简体 / chino simplificado), 日本語 (japonés), Español,\nFrançais (francés) y Deutsch (alemán). Detecta automáticamente la configuración regional de tu sistema en\nel primer arranque; cámbiala en cualquier momento en **Settings → Appearance → Language**, o inícialo\ncon, por ejemplo, `LANG=ja_JP.UTF-8 skc`. Las cadenas no traducidas recurren al inglés, y\nlos nombres de marca/técnicos (Claude, OpenAI, MCP, …) se mantienen literales en todas las configuraciones regionales.\n\n## ¿Qué es Sayknow-CLI?\n\nSayknow-CLI (`skc`) es un arnés externo de agentes de codificación. Se ejecuta desde el repositorio o worktree que elijas y luego le da al agente una superficie de flujo de trabajo pequeña y explícita:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nIntencionadamente no es un plugin oculto para Codex CLI, Claude Code, OpenCode o Claw Code. Inicia `skc` junto a esas herramientas cuando quieras planificación estructurada, evidencia persistente, workers respaldados por tmux o un worktree aislado.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # o: bun install -g sayknow-cli\nskc --version\n```\n\nEl paquete incluye binarios nativos precompilados para macOS, Linux y Windows, así que no necesitas Rust ni paso de compilación. Para actualizar: `npm install -g sayknow-cli@latest` o ejecuta `skc update` en la terminal.\n\n> ¿Vienes de una instalación desde el código fuente (git clone)? Cambia una sola vez: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Para la instalación desde el código (desarrollo), consulta el [README en inglés](../../README.md#install-from-source-development).\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nDentro de una sesión de SKC, usa la superficie pública del flujo de trabajo:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nAñade `skc team ...` solo cuando los workers coordinados de tmux ayuden de forma significativa.\n\n## Capacidades principales\n\n- **Entrevistar antes de suponer**: `deep-interview` convierte solicitudes vagas en requisitos concretos.\n- **Planificar antes de mutar**: `ralplan` revisa el enfoque antes de los cambios de código.\n- **Ejecutar con evidencia**: `ultragoal` rastrea objetivos, revisiones, comprobaciones y evidencia de finalización.\n- **Paralelizar cuando sea útil**: `team` coordina workers respaldados por tmux para tareas más grandes.\n- **Mantenerse externo y revisable**: ejecútalo desde un repositorio o worktree elegido sin parchear otro runtime de agente.\n- **Seguir adelante cuando falla un proveedor**: cuando el modelo predeterminado está bloqueado (sin credenciales, sin cuota, errores de autenticación o del servidor), la sesión continúa con un modelo de otro proveedor; `/fallback` muestra y edita esa cadena. Un paso interrumpido por un reinicio o un fallo transitorio se reanuda solo una vez, con el mismo modelo. Las respuestas de cuota como Z.AI `1113` pasan al siguiente modelo tras una sola solicitud en lugar de agotar el presupuesto de reintentos.\n- **Las sesiones largas no se salen de la ventana de contexto**: tras la compactación, Codex parte de una base nueva visible para el proveedor en lugar de crecer hasta `context_length_exceeded`, y los resúmenes de compactación se redactan para que los proveedores no los rechacen.\n- **Encontrar código por su significado**: la herramienta `locate` encuentra dónde vive un comportamiento a partir de una descripción en lenguaje natural cuando no tienes un nombre que buscar con grep.\n- **Llevar cada trabajo al modelo adecuado**: `/model` asigna modelos por rol y por uso detallado; las tareas de subagentes declaran una `specialty` para caer en el modelo que elegiste para ese tipo de trabajo.\n- **Entregar desde la sesión**: las herramientas `github` y `gitlab` abren e inspeccionan pull/merge requests y CI sin salir de SKC.\n- **Demostrar que las pruebas se ejecutaron sobre este código**: el plugin `verification-receipts` guarda un recibo de cada ejecución de pruebas y te avisa cuando el código ha cambiado desde entonces.\n- **Volver a cualquier sesión**: selector de reanudación con `alt+r`, `ctrl+q` para continuar la más reciente, `/star`, `/fork`, `/rename` y `/import-session` para transcripciones de Codex y Claude Code.\n\n## Superficie del flujo de trabajo\n\nSayknow-CLI incluye cuatro skills de flujo de trabajo predeterminadas:\n\n| Skill | Qué hace |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Aclara requisitos ambiguos antes de planificar o cambiar código. |\n| `ralplan` | Construye y critica un plan de implementación antes de mutar. |\n| `ultragoal` | Rastrea objetivos a través de ejecución, revisión, verificación y evidencia. |\n| `team` | Coordina workers respaldados por tmux cuando vale la pena la ejecución paralela. |\n\nY cuatro agentes de rol incluidos:\n\n| Agent | Qué hace |\n| ----------- | -------------------------------------------------- |\n| `executor` | Implementación acotada, correcciones y refactorizaciones. |\n| `architect` | Evaluación de arquitectura y revisión de código de solo lectura. |\n| `planner` | Secuenciación y criterios de aceptación de solo lectura. |\n| `critic` | Crítica de planes y revisión de accionabilidad de solo lectura. |\n\nSin un zoológico de skills predeterminadas desbordante: SKC mejora haciendo mejor este pequeño método.\n\n## Herramientas integradas\n\nEl agente trabaja con estas herramientas. Las marcadas como *opt-in* permanecen desactivadas hasta que las actives en **Settings → Tools** (o con la clave indicada en `~/.skc/config.yml`).\n\n| Área | Herramientas |\n| ---- | ----- |\n| Archivos y código | `read`, `write`, `edit`, `find`, `search`, `locate` (encuentra código por descripción), `ast_grep` / `ast_edit` (búsqueda y reescritura sensibles a la sintaxis), `lsp` |\n| Shell y runtime | `bash`, `eval` (celdas JS/Python), `ssh`, `debug`, `bisect`, `calc` |\n| Delegación y seguimiento | `task` (subagentes), `subagent`, `job`, `monitor`, `cron`, `irc` (para hablar con agentes en ejecución), `todo_write`, `goal`, `checkpoint` / `rewind` |\n| Alojamiento Git | `github` (*opt-in*, `github.enabled`): pull requests, pushes y ejecuciones de CI mediante `gh` · `gitlab` (*opt-in*, `gitlab.enabled`, requiere [`glab`](https://gitlab.com/gitlab-org/cli)): `mr_create` (devuelve la MR abierta en lugar de crear un duplicado), `mr_view`, `mr_list`, `ci_status` para gitlab.com e instancias autoalojadas |\n| Web y dispositivos | `web_search`, `browser`, `computer`, `render_mermaid` |\n| Descubrimiento | `search_tool_bm25` (activa bajo demanda herramientas ocultas y de MCP), `skill`, `skill_discovery`, `ask` |\n\nElige el conjunto de herramientas de una sola ejecución con `--tools read,bash,...`; ahí también se aceptan nombres de herramientas de plugins, personalizadas y de MCP.\n\n## Plugins\n\nSKC carga paquetes de plugins (herramientas, hooks, skills, servidores MCP) que se verifican por hash al instalarse y se ponen en cuarentena si algún archivo cambia después. Gestiónalos con `skc plugin install|list|...`.\n\n**`verification-receipts`** (incluido en este repositorio) responde a la pregunta «¿pasaron de verdad las pruebas sobre el código que hay ahora?»:\n\n- `verification_run` ejecuta archivos de prueba explícitos con `bun test` o `node --test` y guarda un recibo inmutable: recuentos de aprobados/fallidos por archivo más una huella del árbol de trabajo.\n- `verification_status` recalcula esa huella sin volver a ejecutar las pruebas e informa `fresh`, o `stale` en cuanto el código ha cambiado.\n- `verification_loop` y sus hooks te avisan cuando una `task` en segundo plano termina sin un recibo fresh.\n\nEs solo orientativo, funciona únicamente en POSIX y necesita Node 24.11.1+ para `node --test`. No forma parte del paquete npm; instálalo desde una copia local del repositorio:\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Funciona junto a tu agente o bot existente\n\n| Herramienta o bot | Comando SKC recomendado | Límite |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` o `skc` | `--worktree` nombra un worktree hermano gestionado por SKC; para una ruta existente, haz `cd` allí primero. |\n| Claude Code | `skc --tmux` o `skc --tmux --worktree <name>` | SKC no se convierte en una extensión de Claude Code. |\n| OpenCode | `skc` o `skc --tmux` | Solo flujo de trabajo de ejecutor externo por ahora. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC no se instala dentro de Claw Code ni lo reemplaza. |\n| Controlador / bot externo | `skc mcp-serve coordinator` más `skc setup hermes` para una configuración compatible, o `skc --mode rpc` para un worker en subproceso | Cualquier bot con capacidad MCP/RPC controla SKC mediante el contrato genérico coordinator/RPC, no mediante scraping del scrollback. |\n\nPara la configuración genérica de bots de terceros y pruebas de humo independientes del proveedor, consulta [`docs/bot-integration.md`](docs/bot-integration.md). Para la clasificación de preparación a través de las superficies MCP, RPC, ACP y Bridge/HTTPS, consulta [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Para los detalles de protocolo de más bajo nivel, consulta [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) y [`docs/bridge.md`](docs/bridge.md). Para la hoja de ruta de las superficies de operador remoto, consulta [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (volante web) y [`docs/telegram-remote.md`](docs/telegram-remote.md) (botón de ciclo de vida de Telegram).\n\n## Configuration\n\nEl comportamiento de reintento, reanudación y fallback del proveedor vive en `~/.skc/config.yml` (los valores de abajo son los predeterminados):\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # reanuda una sola vez un paso interrumpido, con el mismo modelo\n maxSilentTimeouts: 3 # se detiene tras este número de timeouts sin salida\nfallback:\n auto: true # continúa con otro proveedor autenticado si el modelo predeterminado está bloqueado\n maxAttempts: 3 # intentos por modelo de la cadena antes de pasar al siguiente\n```\n\n`requestMaxRetries` se aplica antes de que se establezca un stream. `streamMaxRetries` se aplica solo a fallos transitorios de stream que son seguros de reproducir. La autenticación inválida, los modelos/proveedores no compatibles, las solicitudes malformadas, el desbordamiento de contexto, las cancelaciones del usuario y los fallos permanentes de cuota fallan rápido en el modelo actual; con `fallback.auto`, un modelo predeterminado bloqueado cede entonces el relevo al siguiente modelo de la cadena (`/fallback` la muestra y la edita).\n\n## Identidad de la TUI\n\nLa identidad predeterminada de la TUI es el tema **ink-octopus** de SKC — tinta de pulpo: grafito cálido, texto color papel y un único acento ámbar — para terminales oscuras, con **blue-octopus** para terminales claras. También se incluye una variante cálida **red-octopus** para quienes prefieren una paleta más oscura y de alto contraste. Tres temas de migración adicionales — `claude-code`, `codex` y `opencode` — reflejan el aspecto de esas herramientas para facilitar la migración visual y se pueden seleccionar desde Settings o `/theme`. Los ajustes de tema explícitos del usuario siguen prevaleciendo.\n\n### Cuadrícula de temas incluidos\n\nElige desde Settings (`Appearance -> Dark theme` / `Light theme`) o `/theme`.\n\n| Tema | Sensación visual | Mejor uso |\n| --- | --- | --- |\n| `blue-octopus` | Paleta de pulpo azul con acentos azul-tentáculo. | Predeterminado para terminales claras. |\n| `red-octopus` | Variante cálida de pulpo rojo con fuerte contraste de estado. | Alternativa oscura de alto contraste. |\n| `ink-octopus` | Tinta de pulpo — fondo grafito cálido, texto color papel y un único acento ámbar. | Predeterminado para terminales oscuras. |\n| `glow-octopus` | Bioluminiscencia abisal — negro verdiazulado con verde brillante y violeta como secundario. | Terminales oscuras que quieren un acento vivo. |\n| `violet-octopus` | Oscuro ciruela con acentos lavanda y albaricoque como secundario. | Alternativa oscura suave y colorida. |\n| `claude-code` | Paleta oscura inspirada en Claude Code con resaltados terracota y rosa. | Memoria muscular de Claude Code sin salir de SKC. |\n| `codex` | Paleta nítida azul-gris oscuro con un contraste de sesión de codificación más marcado. | Un espacio de trabajo oscuro al estilo Codex. |\n| `opencode` | Paleta oscura inspirada en OpenCode con acentos de terminal más vibrantes. | Memoria muscular de OpenCode en el selector incluido. |\n\n## Development\n\nInstala las dependencias, compila los bindings nativos y configura los valores predeterminados locales:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nEl binario `.node` para `@sayknow-cli/natives` está en gitignore y es necesario antes de cualquier invocación del CLI (`install:defaults`, `dev:link`, tests).\n\n### Canónico: compilar y enlazar el `skc` de desarrollo\n\nPara hacer que el comando global `skc` ejecute **el código fuente TypeScript de esta copia** (sensible a cada edición, con skills/natives funcionando), enlázalo a tu `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` crea un symlink de `skc` → `packages/coding-agent/src/cli.ts` en `~/.local/bin` (sobrescríbelo con `SKC_DEV_LINK_DIR`), reemplaza ese objetivo gestionado, advierte y falla si otro `skc` aún lo oculta antes en `PATH`, y ejecuta `--smoke-test` para confirmar que `@sayknow-cli/natives` carga. Usa `bun run install:dev` para el bootstrap completo (install + link + `setup defaults`).\n\nComprueba en cualquier momento si tu `skc` se ha desviado (fuente incorrecta, o un binario compilado que no puede cargar skills):\n\n```sh\nbun run dev:doctor\n```\n\n> **No** uses el binario compilado para el desarrollo diario. `bun --cwd=packages/coding-agent run build` produce un `dist/skc` independiente, pero un binario `bun build --compile` no puede cargar dinámicamente `@sayknow-cli/natives`, por lo que las skills fallan con `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`. Ejecutar desde el código fuente mediante `dev:link` evita esto. Compila el binario solo al validar una release.\n\nEjecuta el CLI directamente desde el código fuente sin enlazarlo:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nLas definiciones de flujo de trabajo predeterminadas viven en el código fuente, no en copias `.skc` comprometidas:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nPara cambios en las definiciones de flujo de trabajo o en la superficie de rebranding, ejecuta las puertas del proyecto:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nPara un mapa paquete por paquete, consulta [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Contributors\n\nLas contribuciones, los informes de errores y la validación de releases son bienvenidos a través de GitHub Issues y Pull Requests.\n\n## Inspiraciones y linaje\n\nLa identidad predeterminada de la TUI de Sayknow-CLI es la familia de pulpos: ink-octopus como predeterminado oscuro, blue-octopus como predeterminado claro y red-octopus, glow-octopus y violet-octopus como alternativas. También incluye los temas de migración `claude-code`, `codex` y `opencode`, cuyas paletas están inspiradas en esas herramientas para que los usuarios que migran de ellas obtengan un aspecto familiar. Se basa en las lecciones de una pequeña familia de arneses de agentes mientras mantiene la superficie pública de SKC intencionadamente enfocada. La atribución histórica se conserva en [`NOTICE.md`](NOTICE.md).\n\n## License\n\nMIT. Consulta [`LICENSE`](LICENSE).\n",
|
|
75
|
+
"readme/README.fr.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Illustration héros de l'agent de codage autonome Sayknow-CLI\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>Coder devrait ressembler à réfléchir.</strong><br />\n Un exécuteur d'agent de codage ciblé pour les entretiens, les plans révisés, l'exécution native tmux et la vérification durable.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <b>Français</b> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Mascotte personnage de Sayknow-CLI\" width=\"320\" />\n</p>\n\n> Sayknow-CLI est un projet expérimental en phase bêta. Attendez-vous à des aspérités et vérifiez les résultats avant de vous y fier pour un travail important.\n\n## Languages\n\nL'interface est localisée en **7 langues** — English, 한국어 (coréen),\n中文 (简体 / chinois simplifié), 日本語 (japonais), Español (espagnol),\nFrançais (français) et Deutsch (allemand). Elle détecte automatiquement la locale de votre système au\npremier lancement ; changez-en à tout moment dans **Settings → Appearance → Language**, ou lancez\navec par exemple `LANG=ja_JP.UTF-8 skc`. Les chaînes non traduites se rabattent sur l'anglais, et\nles noms de marque/techniques (Claude, OpenAI, MCP, …) restent verbatim dans toutes les locales.\n\n## What is Sayknow-CLI?\n\nSayknow-CLI (`skc`) est un harnais d'agent de codage externe. Il s'exécute depuis le dépôt ou le worktree que vous choisissez, puis donne à l'agent une surface de workflow réduite et explicite :\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nCe n'est volontairement pas un plugin caché pour Codex CLI, Claude Code, OpenCode ou Claw Code. Lancez `skc` à côté de ces outils lorsque vous voulez une planification structurée, des preuves persistantes, des workers adossés à tmux, ou un worktree isolé.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # ou : bun install -g sayknow-cli\nskc --version\n```\n\nLe paquet embarque des binaires natifs précompilés pour macOS, Linux et Windows : aucune chaîne d'outils Rust ni étape de compilation. Pour mettre à jour : `npm install -g sayknow-cli@latest` ou lancez `skc update` dans le terminal.\n\n> Vous veniez d'une installation depuis les sources (git clone) ? Basculez une seule fois : `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Pour l'installation depuis les sources (développement), voir le [README en anglais](../../README.md#install-from-source-development).\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nÀ l'intérieur d'une session SKC, utilisez la surface de workflow publique :\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\nAjoutez `skc team ...` uniquement lorsque des workers tmux coordonnés aident concrètement.\n\n## Core capabilities\n\n- **Interviewer avant de deviner** : `deep-interview` transforme des demandes vagues en exigences concrètes.\n- **Planifier avant de muter** : `ralplan` révise l'approche avant les changements de code.\n- **Exécuter avec des preuves** : `ultragoal` suit les objectifs, les révisions, les vérifications et les preuves de complétion.\n- **Paralléliser quand c'est utile** : `team` coordonne des workers adossés à tmux pour les tâches plus importantes.\n- **Rester externe et révisable** : exécutez depuis un dépôt ou un worktree choisi sans patcher un autre runtime d'agent.\n- **Continuer quand un provider tombe** : quand le modèle par défaut est bloqué (identifiants absents, quota, erreurs d'authentification ou serveur), la session continue sur un modèle d'un autre provider ; `/fallback` affiche et modifie cette chaîne. Une étape interrompue par un redémarrage ou un échec transitoire reprend d'elle-même une fois, sur le même modèle. Les réponses de quota comme le `1113` de Z.AI passent à la suite après une seule requête au lieu d'épuiser le budget de retry.\n- **Les longues sessions restent dans la fenêtre de contexte** : après une compaction, Codex repart d'une base neuve visible par le provider au lieu de grossir jusqu'à `context_length_exceeded`, et les résumés de compaction sont formulés pour que les providers ne les refusent pas.\n- **Trouver le code par son sens** : l'outil `locate` trouve où se situe un comportement à partir d'une simple description, quand vous n'avez aucun nom à passer à grep.\n- **Router le travail vers le bon modèle** : `/model` attribue les modèles par rôle et par usage détaillé ; les tâches de subagent déclarent une `specialty` pour tomber sur le modèle que vous avez choisi pour ce type de travail.\n- **Livrer depuis la session** : les outils `github` et `gitlab` ouvrent et inspectent les pull/merge requests et la CI sans quitter SKC.\n- **Prouver que les tests ont tourné sur ce code** : le plugin `verification-receipts` enregistre un reçu pour chaque exécution de tests et vous signale quand le code a changé depuis.\n- **Revenir à n'importe quelle session** : sélecteur de reprise `alt+r`, `ctrl+q` pour reprendre la plus récente, `/star`, `/fork`, `/rename` et `/import-session` pour les transcripts Codex et Claude Code.\n\n## Workflow surface\n\nSayknow-CLI fournit quatre skills de workflow par défaut :\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | Clarifie les exigences ambiguës avant la planification ou les changements de code. |\n| `ralplan` | Construit et critique un plan d'implémentation avant la mutation. |\n| `ultragoal` | Suit les objectifs à travers l'exécution, la révision, la vérification et les preuves. |\n| `team` | Coordonne des workers adossés à tmux lorsque l'exécution parallèle en vaut la peine. |\n\nEt quatre agents de rôle inclus :\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | Implémentation bornée, correctifs et refactorisations. |\n| `architect` | Évaluation d'architecture et de revue de code en lecture seule. |\n| `planner` | Séquençage et critères d'acceptation en lecture seule. |\n| `critic` | Critique de plan et revue d'actionnabilité en lecture seule. |\n\nPas de ménagerie tentaculaire de skills par défaut : SKC s'améliore en rendant cette petite méthode meilleure.\n\n## Built-in tools\n\nL'agent travaille à travers ces outils. Les outils marqués *opt-in* restent désactivés tant que vous ne les activez pas dans **Settings → Tools** (ou via la clé indiquée dans `~/.skc/config.yml`).\n\n| Area | Tools |\n| ---- | ----- |\n| Fichiers et code | `read`, `write`, `edit`, `find`, `search`, `locate` (trouver du code à partir d'une description), `ast_grep` / `ast_edit` (recherche et réécriture tenant compte de la syntaxe), `lsp` |\n| Shell et runtime | `bash`, `eval` (cellules JS/Python), `ssh`, `debug`, `bisect`, `calc` |\n| Délégation et suivi | `task` (subagents), `subagent`, `job`, `monitor`, `cron`, `irc` (dialoguer avec les agents en cours d'exécution), `todo_write`, `goal`, `checkpoint` / `rewind` |\n| Hébergement Git | `github` (*opt-in*, `github.enabled`) : pull requests, pushes et exécutions CI via `gh` · `gitlab` (*opt-in*, `gitlab.enabled`, nécessite [`glab`](https://gitlab.com/gitlab-org/cli)) : `mr_create` (renvoie la MR déjà ouverte au lieu d'en créer un doublon), `mr_view`, `mr_list`, `ci_status` pour gitlab.com et les instances auto-hébergées |\n| Web et appareils | `web_search`, `browser`, `computer`, `render_mermaid` |\n| Découverte | `search_tool_bm25` (active à la demande les outils masqués et MCP), `skill`, `skill_discovery`, `ask` |\n\nChoisissez le jeu d'outils d'une exécution avec `--tools read,bash,...` ; les noms d'outils de plugins, personnalisés et MCP y sont aussi acceptés.\n\n## Plugins\n\nSKC charge des bundles de plugins (outils, hooks, skills, serveurs MCP) dont le hash est vérifié à l'installation et qui sont mis en quarantaine si un fichier change par la suite. Gérez-les avec `skc plugin install|list|...`.\n\n**`verification-receipts`** (inclus dans ce dépôt) répond à la question « les tests passent-ils vraiment sur le code tel qu'il est maintenant ? » :\n\n- `verification_run` exécute des fichiers de test explicites avec `bun test` ou `node --test` et enregistre un reçu immuable : le nombre de réussites/échecs par fichier, plus une empreinte de l'arbre de travail.\n- `verification_status` recalcule cette empreinte sans relancer les tests et indique `fresh`, ou `stale` dès que le code a changé.\n- `verification_loop` et ses hooks vous préviennent quand une `task` en arrière-plan s'est terminée sans reçu à jour.\n\nIl est purement indicatif, réservé à POSIX, et nécessite Node 24.11.1+ pour `node --test`. Il ne fait pas partie du paquet npm ; installez-le depuis un checkout :\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` nomme un worktree frère géré par SKC ; pour un chemin existant, faites d'abord `cd` à cet endroit. |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC ne devient pas une extension de Claude Code. |\n| OpenCode | `skc` or `skc --tmux` | Workflow d'exécuteur externe uniquement aujourd'hui. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC ne s'installe pas dans Claw Code et ne le remplace pas. |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | Tout bot capable de MCP/RPC pilote SKC via le contrat générique coordinator/RPC, et non par grattage de scrollback. |\n\nPour la configuration générique d'un bot tiers et les smokes indépendants du provider, voir [`docs/bot-integration.md`](docs/bot-integration.md). Pour la classification de readiness à travers les surfaces MCP, RPC, ACP et Bridge/HTTPS, voir [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Pour les détails de protocole de plus bas niveau, voir [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) et [`docs/bridge.md`](docs/bridge.md). Pour la roadmap des surfaces d'opérateur distant, voir [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (volant de direction web) et [`docs/telegram-remote.md`](docs/telegram-remote.md) (bouton de cycle de vie Telegram).\n\n## Configuration\n\nLe comportement de retry, de reprise et de fallback du provider se trouve dans `~/.skc/config.yml` (les valeurs ci-dessous sont celles par défaut) :\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # reprendre une seule fois une étape interrompue, sur le même modèle\n maxSilentTimeouts: 3 # s'arrêter après ce nombre de timeouts sans aucune sortie\nfallback:\n auto: true # continuer sur un autre provider connecté quand le modèle par défaut est bloqué\n maxAttempts: 3 # tentatives par modèle de la chaîne avant de passer au suivant\n```\n\n`requestMaxRetries` s'applique avant qu'un stream ne soit établi. `streamMaxRetries` ne s'applique qu'aux échecs de stream transitoires sûrs pour le replay. L'authentification invalide, les modèles/providers non pris en charge, les requêtes malformées, le débordement de contexte, les abandons par l'utilisateur et les échecs de quota permanents échouent immédiatement sur le modèle courant ; avec `fallback.auto`, un modèle par défaut bloqué passe ensuite la main au modèle suivant de la chaîne (`/fallback` l'affiche et la modifie).\n\n## TUI identity\n\nL'identité TUI par défaut est le thème SKC **ink-octopus** — encre de poulpe : graphite chaud, texte couleur papier, un seul accent ambre — pour les terminaux sombres, avec **blue-octopus** pour les terminaux clairs. Une variante chaleureuse **red-octopus** est également incluse pour ceux qui préfèrent une palette plus sombre et à fort contraste. Trois thèmes de migration supplémentaires — `claude-code`, `codex` et `opencode` — reflètent l'apparence de ces outils pour faciliter la migration visuelle et sont sélectionnables depuis Settings ou `/theme`. Les réglages de thème explicites de l'utilisateur l'emportent toujours.\n\n### Bundled theme grid\n\nChoisissez depuis Settings (`Appearance -> Dark theme` / `Light theme`) ou `/theme`.\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | Palette poulpe bleu avec des accents bleu tentacule. | Par défaut pour les terminaux clairs. |\n| `red-octopus` | Variante chaleureuse poulpe rouge avec un fort contraste d'état. | Alternative sombre à fort contraste. |\n| `ink-octopus` | Encre de poulpe — fond graphite chaud, texte couleur papier, un seul accent ambre. | Par défaut pour les terminaux sombres. |\n| `glow-octopus` | Bioluminescence abyssale — noir sarcelle avec un vert lumineux et un violet secondaire. | Terminaux sombres qui veulent un accent vif. |\n| `violet-octopus` | Sombre prune avec des accents lavande et un abricot secondaire. | Alternative sombre douce et colorée. |\n| `claude-code` | Palette sombre inspirée de Claude Code avec des touches terracotta et rose. | La mémoire musculaire de Claude Code sans quitter SKC. |\n| `codex` | Palette bleu-gris sombre et nette avec un contraste de session de codage plus marqué. | Un espace de travail sombre à la manière de Codex. |\n| `opencode` | Palette sombre inspirée d'OpenCode avec des accents de terminal plus percutants. | La mémoire musculaire d'OpenCode dans le sélecteur inclus. |\n\n## Development\n\nInstallez les dépendances, compilez les bindings natifs et configurez les valeurs par défaut locales :\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\nLe binaire `.node` pour `@sayknow-cli/natives` est gitignored et requis avant toute invocation de la CLI (`install:defaults`, `dev:link`, tests).\n\n### Canonical: build and link the dev `skc`\n\nPour que la commande globale `skc` exécute **la source TypeScript de ce checkout** (sensible à chaque édition, avec skills/natives fonctionnels), liez-la à votre `PATH` :\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` crée un lien symbolique `skc` → `packages/coding-agent/src/cli.ts` dans `~/.local/bin` (à surcharger avec `SKC_DEV_LINK_DIR`), remplace cette cible gérée, avertit et échoue si un autre `skc` le masque encore plus tôt sur le `PATH`, et exécute `--smoke-test` pour confirmer que `@sayknow-cli/natives` se charge. Utilisez `bun run install:dev` pour le bootstrap complet (install + link + `setup defaults`).\n\nVérifiez à tout moment si votre `skc` a dérivé (mauvaise source, ou un binaire compilé qui ne peut pas charger les skills) :\n\n```sh\nbun run dev:doctor\n```\n\n> N'utilisez **pas** le binaire compilé pour le développement quotidien. `bun --cwd=packages/coding-agent run build` produit un `dist/skc` autonome, mais un binaire `bun build --compile` ne peut pas charger dynamiquement `@sayknow-cli/natives`, donc les skills échouent avec `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`. L'exécution depuis la source via `dev:link` évite cela. Ne compilez le binaire que lors de la validation d'une release.\n\nExécutez la CLI depuis la source directement sans lier :\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nLes définitions de workflow par défaut résident dans la source, et non dans des copies `.skc` commitées :\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nPour les changements de définition de workflow ou de surface de rebrand, exécutez les portes du projet :\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nPour une carte package par package, voir [`docs/codebase-overview.md`](docs/codebase-overview.md).\n\n## Contributors\n\nLes contributions, les rapports de bugs et la validation de release sont les bienvenus via les GitHub Issues et les Pull Requests.\n\n## Inspirations and lineage\n\nL'identité TUI par défaut de Sayknow-CLI est la famille de poulpes : ink-octopus par défaut en sombre, blue-octopus par défaut en clair, et red-octopus, glow-octopus et violet-octopus en alternatives. Il inclut aussi les thèmes de migration `claude-code`, `codex` et `opencode` dont les palettes sont inspirées de ces outils afin que les utilisateurs qui en proviennent retrouvent une apparence familière. Il s'appuie sur les leçons d'une petite famille de harnais d'agents tout en gardant la surface publique SKC volontairement ciblée. L'attribution historique est conservée dans [`NOTICE.md`](NOTICE.md).\n\n## License\n\nMIT. Voir [`LICENSE`](LICENSE).\n",
|
|
76
|
+
"readme/README.ja.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI 自律型コーディングエージェントのヒーローイラスト\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>コーディングは、考えることのように感じられるべきだ。</strong><br />\n インタビュー、レビュー済みプラン、tmux ネイティブ実行、そして永続的な検証のための、集中型コーディングエージェントランナー。\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <a href=\"README.zh.md\">中文</a> ·\n <b>日本語</b> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI キャラクターマスコット\" width=\"320\" />\n</p>\n\n> Sayknow-CLI は実験的なベータ段階のプロジェクトです。粗削りな部分があることを想定し、重要な作業で頼る前には出力を検証してください。\n\n## Languages\n\nインターフェースは **7 言語** にローカライズされています — English、한국어 (韓国語)、\n中文 (简体 / 簡体字中国語)、日本語 (Japanese)、Español (スペイン語)、\nFrançais (フランス語)、そして Deutsch (ドイツ語)。初回起動時にシステムロケールを\n自動検出します。**Settings → Appearance → Language** でいつでも切り替えられるほか、\nたとえば `LANG=ja_JP.UTF-8 skc` のように起動することもできます。未翻訳の文字列は英語に\nフォールバックし、ブランド名や技術名 (Claude、OpenAI、MCP、…) はすべてのロケールで\nそのまま表示されます。\n\n## Sayknow-CLI とは?\n\nSayknow-CLI (`skc`) は外部コーディングエージェントのハーネスです。選択したリポジトリまたは worktree から実行され、エージェントに対して小さく明示的なワークフロー面を提供します:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\nこれは意図的に、Codex CLI、Claude Code、OpenCode、Claw Code 向けの隠しプラグインにはなっていません。構造化されたプランニング、永続的なエビデンス、tmux ベースのワーカー、または分離された worktree が欲しいときに、それらのツールと並べて `skc` を起動してください。\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # または: bun install -g sayknow-cli\nskc --version\n```\n\nmacOS・Linux・Windows 向けのビルド済みネイティブを同梱しているため、Rust ツールチェーンやビルド手順は不要です。更新は `npm install -g sayknow-cli@latest`、またはターミナルで `skc update`。\n\n> 以前ソース(git clone)からインストールした場合は、一度だけ `rm -f ~/.local/bin/skc && npm install -g sayknow-cli` で切り替えてください。ソース/開発インストールは[英語版 README](../../README.md#install-from-source-development)を参照。\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nSKC セッション内では、公開されているワークフロー面を使用してください:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n`skc team ...` は、協調する tmux ワーカーが実質的に役立つときにのみ追加してください。\n\n## Core capabilities\n\n- **推測する前にインタビューする**: `deep-interview` は曖昧なリクエストを具体的な要件に変えます。\n- **変更する前にプランニングする**: `ralplan` はコード変更の前にアプローチをレビューします。\n- **エビデンスとともに実行する**: `ultragoal` はゴール、リビジョン、チェック、完了エビデンスを追跡します。\n- **役立つときに並列化する**: `team` はより大きなタスクのために tmux ベースのワーカーを協調させます。\n- **外部かつレビュー可能であり続ける**: 別のエージェントランタイムにパッチを当てることなく、選択したリポジトリまたは worktree から実行します。\n- **プロバイダーが失敗しても作業を続ける**: デフォルトモデルがブロックされたとき (認証情報なし、クォータ超過、認証エラーやサーバーエラー)、セッションは別プロバイダーのモデルで続行します。このチェーンは `/fallback` で確認・編集できます。再起動や一時的な障害で中断したステップは、同じモデルで一度だけ自動的に再開します。Z.AI `1113` のようなクォータ応答では、リトライバジェットを使い果たさずに 1 回のリクエストで次へ進みます。\n- **長いセッションでもコンテキストウィンドウに収める**: コンパクション後、Codex は `context_length_exceeded` に向かって膨らみ続けるのではなく、プロバイダーから見える新しいベースラインから再開します。また、コンパクションの要約はプロバイダーに拒否されない表現で書かれます。\n- **意味でコードを探す**: `locate` ツールは、grep する名前がなくても、平易な説明から該当する振る舞いがどこにあるかを見つけます。\n- **作業を適切なモデルに振り分ける**: `/model` でロールごと、さらに詳細な用途ごとにモデルを割り当てます。サブエージェントのタスクは `specialty` を宣言し、その種類の作業用に選んだモデルで実行されます。\n- **セッションを離れずにシップする**: `github` と `gitlab` ツールで、SKC から離れることなくプル/マージリクエストを作成・確認し、CI も確認できます。\n- **テストがこのコードで実行されたことを証明する**: `verification-receipts` プラグインはテスト実行ごとにレシートを保存し、その後コードが変更されたら知らせます。\n- **どのセッションにも戻れる**: `alt+r` の再開ピッカー、最新のセッションを続ける `ctrl+q`、`/star`、`/fork`、`/rename`、そして Codex と Claude Code のトランスクリプトを取り込む `/import-session`。\n\n## Workflow surface\n\nSayknow-CLI は 4 つのデフォルトワークフロースキルを同梱しています:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | プランニングやコード変更の前に、曖昧な要件を明確化します。 |\n| `ralplan` | 変更の前に実装プランを構築し批評します。 |\n| `ultragoal` | 実行、リビジョン、検証、エビデンスを通じてゴールを追跡します。 |\n| `team` | 並列実行に価値があるときに tmux ベースのワーカーを協調させます。 |\n\nそして 4 つの同梱ロールエージェント:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 範囲を限定した実装、修正、リファクタリング。 |\n| `architect` | 読み取り専用のアーキテクチャおよびコードレビュー評価。 |\n| `planner` | 読み取り専用のシーケンシングと受け入れ基準。 |\n| `critic` | 読み取り専用のプラン批評と実行可能性レビュー。 |\n\n肥大化したデフォルトスキルの動物園はありません: SKC はこの小さなメソッドをより良くすることで改善されます。\n\n## Built-in tools\n\nエージェントは以下のツールを通じて作業します。*opt-in* と記されたツールは、**Settings → Tools** (または `~/.skc/config.yml` の該当キー) で有効にするまでオフのままです。\n\n| Area | Tools |\n| ---- | ----- |\n| ファイルとコード | `read`、`write`、`edit`、`find`、`search`、`locate` (説明からコードを探す)、`ast_grep` / `ast_edit` (構文を理解した検索と書き換え)、`lsp` |\n| シェルとランタイム | `bash`、`eval` (JS/Python セル)、`ssh`、`debug`、`bisect`、`calc` |\n| 委任とトラッキング | `task` (サブエージェント)、`subagent`、`job`、`monitor`、`cron`、`irc` (実行中のエージェントと会話)、`todo_write`、`goal`、`checkpoint` / `rewind` |\n| Git ホスティング | `github` (*opt-in*、`github.enabled`): `gh` を通じたプルリクエスト、プッシュ、CI 実行 · `gitlab` (*opt-in*、`gitlab.enabled`、[`glab`](https://gitlab.com/gitlab-org/cli) が必要): `mr_create` (重複を作らず、既にオープンな MR を返す)、`mr_view`、`mr_list`、`ci_status`。gitlab.com とセルフホストのインスタンスに対応 |\n| Web とデバイス | `web_search`、`browser`、`computer`、`render_mermaid` |\n| ディスカバリー | `search_tool_bm25` (非表示ツールや MCP ツールを必要に応じて有効化)、`skill`、`skill_discovery`、`ask` |\n\n1 回の実行で使うツールセットは `--tools read,bash,...` で選べます。プラグイン、カスタム、MCP のツール名もここで指定できます。\n\n## Plugins\n\nSKC はプラグインバンドル (ツール、フック、スキル、MCP サーバー) を読み込みます。バンドルはインストール時にハッシュで検証され、その後ファイルが変更されると隔離されます。管理には `skc plugin install|list|...` を使います。\n\n**`verification-receipts`** (このリポジトリに同梱) は「今あるコードで、テストは本当に通ったのか?」に答えます:\n\n- `verification_run` は指定したテストファイルを `bun test` または `node --test` で実行し、変更不可のレシートを保存します: ファイルごとの成功/失敗件数と、作業ツリーのフィンガープリントです。\n- `verification_status` はテストを再実行せずにそのフィンガープリントを再計算し、`fresh` か、コードが変更されて `stale` になったかを報告します。\n- `verification_loop` とそのフックは、バックグラウンドの `task` が最新のレシートなしで終了したときに知らせます。\n\nこれは参考情報を示すだけ (advisory) で、POSIX 専用です。`node --test` には Node 24.11.1+ が必要です。npm パッケージには含まれないため、チェックアウトからインストールしてください:\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` は SKC が管理する兄弟 worktree に名前を付けます。既存のパスを使う場合は、まずそこへ `cd` してください。 |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC は Claude Code の拡張機能にはなりません。 |\n| OpenCode | `skc` or `skc --tmux` | 現時点では外部ランナーのワークフローのみです。 |\n| Claw Code | `skc --tmux --worktree <name>` | SKC は Claw Code にインストールされたり、置き換えたりはしません。 |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | MCP/RPC 対応のボットはどれも、スクロールバックのスクレイピングではなく、汎用のコーディネーター/RPC コントラクトを通じて SKC を駆動します。 |\n\n汎用的なサードパーティボットのセットアップとプロバイダー非依存のスモークテストについては、[`docs/bot-integration.md`](docs/bot-integration.md) を参照してください。MCP、RPC、ACP、Bridge/HTTPS 各面にわたる準備状況の分類については、[`docs/external-control-readiness.md`](docs/external-control-readiness.md) を参照してください。より低レベルのプロトコル詳細については、[`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md)、[`docs/rpc.md`](docs/rpc.md)、および [`docs/bridge.md`](docs/bridge.md) を参照してください。リモートオペレーター面のロードマップについては、[`docs/sayknow-remote.md`](docs/sayknow-remote.md) (web steering wheel) と [`docs/telegram-remote.md`](docs/telegram-remote.md) (Telegram lifecycle button) を参照してください。\n\n## Configuration\n\nプロバイダーのリトライ、再開、フォールバックの動作は `~/.skc/config.yml` で設定します (以下の値がデフォルトです):\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # 中断したステップを同じモデルで一度だけ再開\n maxSilentTimeouts: 3 # 出力のないタイムアウトがこの回数に達したら停止\nfallback:\n auto: true # デフォルトモデルがブロックされたら、ログイン済みの別プロバイダーで続行\n maxAttempts: 3 # チェーン内の次のモデルへ移る前の、モデルごとの試行回数\n```\n\n`requestMaxRetries` はストリームが確立される前に適用されます。`streamMaxRetries` はリプレイ安全な一時的ストリーム障害にのみ適用されます。無効な認証、サポートされていないモデル/プロバイダー、不正な形式のリクエスト、コンテキストオーバーフロー、ユーザーによる中断、および恒久的なクォータ障害は、現在のモデルで即座に失敗 (フェイルファスト) します。`fallback.auto` が有効な場合、ブロックされたデフォルトモデルはチェーン内の次のモデルに引き継がれます (`/fallback` で確認・編集できます)。\n\n## TUI identity\n\nデフォルトの TUI アイデンティティは SKC の **ink-octopus** テーマ — タコの墨: 温かみのあるグラファイト、紙色の文字、琥珀色のアクセント 1 色 — でダークターミナルに適用され、ライトターミナルには **blue-octopus** が適用されます。より暗めでハイコントラストなパレットを好む人のために、温かみのある **red-octopus** バリアントも同梱されています。さらに 3 つの移行用テーマ — `claude-code`、`codex`、`opencode` — がそれらのツールの見た目を再現しており、視覚的な移行を容易にし、Settings または `/theme` から選択できます。ユーザーが明示的に設定したテーマは引き続き優先されます。\n\n### Bundled theme grid\n\nSettings (`Appearance -> Dark theme` / `Light theme`) または `/theme` から選択してください。\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | テンタクルブルーのアクセントを持つ青いタコのパレット。 | ライトターミナルのデフォルト。 |\n| `red-octopus` | 強いステータスコントラストを持つ温かみのある赤いタコのバリアント。 | ハイコントラストなダークの代替。 |\n| `ink-octopus` | タコの墨 — 温かみのあるグラファイト背景、紙色の文字、琥珀色のアクセント 1 色。 | ダークターミナルのデフォルト。 |\n| `glow-octopus` | 深海の生物発光 — ティールがかった黒に発光グリーン、サブにバイオレット。 | 鮮やかなアクセントが欲しいダークターミナル。 |\n| `violet-octopus` | プラム色のダークにラベンダーのアクセント、サブにアプリコット。 | 柔らかくカラフルなダークの代替。 |\n| `claude-code` | テラコッタとピンクのハイライトを持つ Claude Code 風のダークパレット。 | SKC を離れずに Claude Code の体に染み付いた操作感を。 |\n| `codex` | よりシャープなコーディングセッションのコントラストを持つ、くっきりしたダークブルーグレーのパレット。 | Codex ライクなダークワークスペース。 |\n| `opencode` | よりパンチの効いたターミナルアクセントを持つ OpenCode 風のダークパレット。 | 同梱のピッカーで OpenCode の体に染み付いた操作感を。 |\n\n## Development\n\n依存関係をインストールし、ネイティブバインディングをビルドし、ローカルのデフォルトをセットアップします:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives` 用の `.node` バイナリは gitignore されており、あらゆる CLI 呼び出し (`install:defaults`、`dev:link`、テスト) の前に必要です。\n\n### Canonical: build and link the dev `skc`\n\nグローバルの `skc` コマンドが **このチェックアウトの TypeScript ソース** を実行するようにする (すべての編集に即座に反映され、スキル/ネイティブが動作する) には、それをあなたの `PATH` にリンクします:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` は `skc` → `packages/coding-agent/src/cli.ts` を `~/.local/bin` にシンボリックリンクし (`SKC_DEV_LINK_DIR` で上書き可能)、その管理対象ターゲットを置き換え、別の `skc` が `PATH` 上でより前にそれをシャドウしている場合は警告して失敗し、`--smoke-test` を実行して `@sayknow-cli/natives` がロードされることを確認します。完全なブートストラップ (install + link + `setup defaults`) には `bun run install:dev` を使用してください。\n\nあなたの `skc` がドリフトしていないか (誤ったソース、またはスキルをロードできないコンパイル済みバイナリ) は、いつでも確認できます:\n\n```sh\nbun run dev:doctor\n```\n\n> 日常の開発にコンパイル済みバイナリを **使わないでください**。`bun --cwd=packages/coding-agent run build` はスタンドアロンの `dist/skc` を生成しますが、`bun build --compile` のバイナリは `@sayknow-cli/natives` を動的にロードできないため、スキルは `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` で失敗します。`dev:link` を通じてソースから実行すれば、これを回避できます。バイナリのビルドはリリースを検証するときのみ行ってください。\n\nリンクせずに CLI をソースから直接実行します:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\nデフォルトのワークフロー定義はソースにあり、コミットされた `.skc` のコピーにはありません:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\nワークフロー定義またはリブランド面の変更については、プロジェクトのゲートを実行してください:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\nパッケージごとのマップについては、[`docs/codebase-overview.md`](docs/codebase-overview.md) を参照してください。\n\n## Contributors\n\nコントリビューション、バグレポート、リリース検証は GitHub の Issues と Pull Request を通じて歓迎しています。\n\n## Inspirations and lineage\n\nSayknow-CLI のデフォルト TUI アイデンティティはタコのファミリーです: ダークのデフォルト ink-octopus、ライトのデフォルト blue-octopus、そして red-octopus・glow-octopus・violet-octopus の代替。また、`claude-code`、`codex`、`opencode` の移行用テーマも同梱しており、これらのパレットはそれらのツールにインスパイアされているため、移行してくるユーザーが見慣れた見た目を得られます。これは、公開された SKC 面を意図的に集中させたまま、小さなエージェントハーネス一族からの教訓の上に構築されています。歴史的な帰属表示は [`NOTICE.md`](NOTICE.md) に保持されています。\n\n## License\n\nMIT。[`LICENSE`](LICENSE) を参照してください。\n",
|
|
77
|
+
"readme/README.ko.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>코딩은 사고처럼 느껴져야 합니다.</strong><br />\n 인터뷰, 검토된 계획, tmux 네이티브 실행, 견고한 검증을 위한 집중형 코딩 에이전트 러너.\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <b>한국어</b> ·\n <a href=\"README.zh.md\">中文</a> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI는 실험적인 베타 단계 프로젝트입니다. 거친 부분이 있을 수 있으니 중요한 작업에 의존하기 전에 출력 결과를 검증하세요.\n\n## Languages\n\n인터페이스는 **7개 언어** — English, 한국어 (Korean),\n中文 (简体 / Simplified Chinese), 日本語 (Japanese), Español (Spanish),\nFrançais (French), Deutsch (German) — 로 현지화되어 있습니다. 첫 실행 시\n시스템 로케일을 자동으로 감지하며, 언제든지 **Settings → Appearance → Language** 에서\n전환하거나 예를 들어 `LANG=ja_JP.UTF-8 skc` 로 실행할 수 있습니다. 번역되지 않은 문자열은\nEnglish로 대체되며, 브랜드/기술 이름(Claude, OpenAI, MCP, …)은 모든 로케일에서 그대로 유지됩니다.\n\n## What is Sayknow-CLI?\n\nSayknow-CLI(`skc`)는 외부 코딩 에이전트 하니스입니다. 선택한 저장소나 워크트리에서 실행되며, 에이전트에게 작고 명시적인 워크플로 표면을 제공합니다:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\n이것은 의도적으로 Codex CLI, Claude Code, OpenCode, Claw Code의 숨겨진 플러그인이 아닙니다. 구조화된 계획, 지속적인 증거, tmux 기반 워커, 또는 격리된 워크트리를 원할 때 이러한 도구들 옆에서 `skc`를 시작하세요.\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # 또는: bun install -g sayknow-cli\nskc --version\n```\n\n프리빌드 네이티브(macOS·Linux·Windows)가 포함돼 있어 Rust 툴체인이나 빌드가 필요 없습니다. 업데이트는 `npm install -g sayknow-cli@latest` 또는 터미널에서 `skc update`.\n\n> 이전에 소스(git clone)로 설치했다면 한 번만 `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`로 전환하세요. 소스/개발 설치는 [영문 README](../../README.md#install-from-source-development) 참고.\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\nSKC 세션 내부에서는, 공개 워크플로 표면을 사용하세요:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n조율된 tmux 워커가 실질적으로 도움이 될 때만 `skc team ...`을 추가하세요.\n\n## Core capabilities\n\n- **추측하기 전에 인터뷰**: `deep-interview`는 모호한 요청을 구체적인 요구사항으로 바꿉니다.\n- **변경하기 전에 계획**: `ralplan`은 코드 변경 전에 접근 방식을 검토합니다.\n- **증거와 함께 실행**: `ultragoal`은 목표, 수정, 점검, 완료 증거를 추적합니다.\n- **유용할 때 병렬화**: `team`은 더 큰 작업을 위해 tmux 기반 워커를 조율합니다.\n- **외부에서 검토 가능하게 유지**: 다른 에이전트 런타임을 패치하지 않고 선택한 저장소나 워크트리에서 실행합니다.\n- **공급자가 실패해도 계속 진행**: 기본 모델이 막히면(자격 증명 없음, 할당량 소진, 인증·서버 오류) 다른 공급자의 모델로 세션을 이어 갑니다. 이 체인은 `/fallback`으로 확인하고 편집할 수 있습니다. 재시작이나 일시적 실패로 중단된 단계는 같은 모델에서 한 번 자동으로 재개됩니다. Z.AI `1113` 같은 할당량 응답은 재시도 예산을 소모하지 않고 요청 한 번 만에 다음으로 넘어갑니다.\n- **긴 세션도 컨텍스트 윈도 안에서**: 압축(compaction) 후 Codex는 `context_length_exceeded`를 향해 계속 불어나는 대신 공급자에게 보이는 새 기준점에서 다시 시작하며, 압축 요약은 공급자가 거부하지 않도록 작성됩니다.\n- **의미로 코드 찾기**: `locate` 도구는 grep할 이름이 없을 때도 평범한 설명만으로 해당 동작이 어디에 있는지 찾아 줍니다.\n- **작업을 알맞은 모델로 라우팅**: `/model`로 역할별·세부 용도별 모델을 지정합니다. 서브에이전트 작업은 `specialty`를 선언해 그 종류의 작업에 지정한 모델에서 실행됩니다.\n- **세션 안에서 PR/MR까지**: `github`와 `gitlab` 도구로 SKC를 벗어나지 않고 풀/머지 리퀘스트를 열고 살펴보며 CI도 확인합니다.\n- **이 코드에서 테스트가 실행됐음을 증명**: `verification-receipts` 플러그인은 테스트를 실행할 때마다 영수증을 저장하고, 그 뒤로 코드가 바뀌면 알려 줍니다.\n- **어떤 세션으로든 복귀**: `alt+r` 재개 선택기, 최신 세션을 이어 가는 `ctrl+q`, `/star`, `/fork`, `/rename`, 그리고 Codex·Claude Code 대화 기록을 가져오는 `/import-session`.\n\n## Workflow surface\n\nSayknow-CLI는 네 가지 기본 워크플로 스킬을 제공합니다:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | 계획이나 코드 변경 전에 모호한 요구사항을 명확히 합니다. |\n| `ralplan` | 변경 전에 구현 계획을 구축하고 비평합니다. |\n| `ultragoal` | 실행, 수정, 검증, 증거를 거쳐 목표를 추적합니다. |\n| `team` | 병렬 실행이 가치가 있을 때 tmux 기반 워커를 조율합니다. |\n\n그리고 네 가지 번들 역할 에이전트:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 범위가 정해진 구현, 수정, 리팩터. |\n| `architect` | 읽기 전용 아키텍처 및 코드 리뷰 평가. |\n| `planner` | 읽기 전용 순서 결정 및 수용 기준. |\n| `critic` | 읽기 전용 계획 비평 및 실행 가능성 검토. |\n\n광범위한 기본 스킬 동물원은 없습니다: SKC는 이 작은 방법을 더 좋게 만들어 개선됩니다.\n\n## Built-in tools\n\n에이전트는 다음 도구들로 작업합니다. *opt-in*으로 표시된 도구는 **Settings → Tools**(또는 `~/.skc/config.yml`의 해당 키)에서 켜기 전까지 꺼져 있습니다.\n\n| Area | Tools |\n| ---- | ----- |\n| 파일과 코드 | `read`, `write`, `edit`, `find`, `search`, `locate`(설명으로 코드 찾기), `ast_grep` / `ast_edit`(구문을 인식하는 검색과 재작성), `lsp` |\n| 셸과 런타임 | `bash`, `eval`(JS/Python 셀), `ssh`, `debug`, `bisect`, `calc` |\n| 위임과 추적 | `task`(서브에이전트), `subagent`, `job`, `monitor`, `cron`, `irc`(실행 중인 에이전트와 대화), `todo_write`, `goal`, `checkpoint` / `rewind` |\n| Git 호스팅 | `github`(*opt-in*, `github.enabled`): `gh`를 통한 풀 리퀘스트, 푸시, CI 실행 · `gitlab`(*opt-in*, `gitlab.enabled`, [`glab`](https://gitlab.com/gitlab-org/cli) 필요): `mr_create`(중복을 만들지 않고 이미 열린 MR을 반환), `mr_view`, `mr_list`, `ci_status` — gitlab.com과 셀프 호스팅 인스턴스 지원 |\n| 웹과 기기 | `web_search`, `browser`, `computer`, `render_mermaid` |\n| 탐색 | `search_tool_bm25`(숨겨진 도구와 MCP 도구를 필요할 때 활성화), `skill`, `skill_discovery`, `ask` |\n\n한 번의 실행에 쓸 도구 세트는 `--tools read,bash,...`로 고를 수 있으며, 플러그인·커스텀·MCP 도구 이름도 여기에 지정할 수 있습니다.\n\n## Plugins\n\nSKC는 플러그인 번들(도구, 훅, 스킬, MCP 서버)을 로드합니다. 번들은 설치 시점에 해시로 검사되고, 이후 파일이 바뀌면 격리됩니다. 관리는 `skc plugin install|list|...`로 합니다.\n\n**`verification-receipts`**(이 저장소에 번들로 포함)는 \"지금 있는 코드에서 테스트가 실제로 통과했는가?\"에 답합니다:\n\n- `verification_run`은 지정한 테스트 파일을 `bun test` 또는 `node --test`로 실행하고, 변경할 수 없는 영수증을 저장합니다: 파일별 통과/실패 개수와 작업 트리의 지문(fingerprint).\n- `verification_status`는 테스트를 다시 실행하지 않고 그 지문을 다시 계산해, `fresh`인지 아니면 코드가 바뀌어 `stale`인지 보고합니다.\n- `verification_loop`와 그 훅은 백그라운드 `task`가 최신 영수증 없이 끝났을 때 알려 줍니다.\n\n참고용(advisory)이고 POSIX 전용이며, `node --test`를 쓰려면 Node 24.11.1+가 필요합니다. npm 패키지에는 포함되지 않으므로 체크아웃에서 설치하세요:\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree`는 SKC가 관리하는 형제 워크트리의 이름을 지정합니다. 기존 경로의 경우 먼저 그곳으로 `cd` 하세요. |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC는 Claude Code 확장이 되지 않습니다. |\n| OpenCode | `skc` or `skc --tmux` | 현재로서는 외부 러너 워크플로만 지원합니다. |\n| Claw Code | `skc --tmux --worktree <name>` | SKC는 Claw Code에 설치되거나 그것을 대체하지 않습니다. |\n| External controller / bot | 호환 가능한 구성을 위한 `skc mcp-serve coordinator` 및 `skc setup hermes`, 또는 서브프로세스 워커를 위한 `skc --mode rpc` | MCP/RPC 지원 봇이라면 무엇이든 스크롤백 스크래핑이 아니라 일반 coordinator/RPC 계약을 통해 SKC를 구동합니다. |\n\n일반 서드파티 봇 설정 및 공급자 독립적 스모크에 대해서는 [`docs/bot-integration.md`](docs/bot-integration.md)를 참조하세요. MCP, RPC, ACP, Bridge/HTTPS 표면 전반의 준비도 분류에 대해서는 [`docs/external-control-readiness.md`](docs/external-control-readiness.md)를 참조하세요. 더 낮은 수준의 프로토콜 세부 사항에 대해서는 [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md), [`docs/bridge.md`](docs/bridge.md)를 참조하세요. 원격 운영자 표면 로드맵에 대해서는 [`docs/sayknow-remote.md`](docs/sayknow-remote.md)(웹 스티어링 휠) 및 [`docs/telegram-remote.md`](docs/telegram-remote.md)(Telegram 라이프사이클 버튼)를 참조하세요.\n\n## Configuration\n\n공급자 재시도, 재개, 폴백 동작은 `~/.skc/config.yml`에서 설정합니다(아래 값이 기본값입니다):\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # 중단된 단계를 같은 모델에서 한 번 재개\n maxSilentTimeouts: 3 # 출력 없는 타임아웃이 이 횟수만큼 나면 중단\nfallback:\n auto: true # 기본 모델이 막히면 로그인된 다른 공급자로 계속 진행\n maxAttempts: 3 # 체인의 다음 모델로 넘어가기 전 모델당 시도 횟수\n```\n\n`requestMaxRetries`는 스트림이 설정되기 전에 적용됩니다. `streamMaxRetries`는 재생 안전한 일시적 스트림 실패에만 적용됩니다. 잘못된 인증, 지원되지 않는 모델/공급자, 잘못된 형식의 요청, 컨텍스트 오버플로, 사용자 중단, 영구적인 할당량 실패는 현재 모델에서 즉시 실패(fail-fast)합니다. `fallback.auto`가 켜져 있으면 막힌 기본 모델은 체인의 다음 모델로 넘겨집니다(`/fallback`으로 확인하고 편집할 수 있습니다).\n\n## TUI identity\n\n기본 TUI 정체성은 SKC **ink-octopus** 테마 — 문어 먹물: 따뜻한 흑연색, 종이색 글자, 호박색 강조 하나 — 로 다크 터미널에 적용되며, 라이트 터미널에는 **blue-octopus**가 적용됩니다. 더 어둡고 고대비 팔레트를 선호하는 사람들을 위해 따뜻한 **red-octopus** 변형도 번들로 제공됩니다. 세 가지 추가 마이그레이션 테마 — `claude-code`, `codex`, `opencode` — 는 쉬운 눈 마이그레이션을 위해 해당 도구들의 모습을 그대로 따르며 Settings 또는 `/theme`에서 선택할 수 있습니다. 명시적인 사용자 테마 설정이 여전히 우선합니다.\n\n### Bundled theme grid\n\nSettings (`Appearance -> Dark theme` / `Light theme`) 또는 `/theme`에서 선택하세요.\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | 촉수 블루 액센트가 있는 파란 문어 팔레트. | 라이트 터미널의 기본값. |\n| `red-octopus` | 강한 상태 대비를 가진 따뜻한 빨간 문어 변형. | 고대비 다크 대안. |\n| `ink-octopus` | 문어 먹물 — 따뜻한 흑연색 배경, 종이색 글자, 호박색 강조 하나. | 다크 터미널의 기본값. |\n| `glow-octopus` | 심해 생물발광 — 틸빛 어둠에 발광 초록, 보조로 보라. | 선명한 강조색을 원하는 다크 터미널. |\n| `violet-octopus` | 자줏빛 어둠에 라벤더 강조, 보조로 살구색. | 부드럽고 화사한 다크 대안. |\n| `claude-code` | 테라코타와 핑크 하이라이트가 있는 Claude Code 영감 다크 팔레트. | SKC를 떠나지 않고 Claude Code 근육 기억을 유지. |\n| `codex` | 더 날카로운 코딩 세션 대비를 가진 선명한 다크 블루그레이 팔레트. | Codex 같은 다크 작업 공간. |\n| `opencode` | 더 강렬한 터미널 액센트를 가진 OpenCode 영감 다크 팔레트. | 번들 선택기에서의 OpenCode 근육 기억. |\n\n## Development\n\n의존성을 설치하고, 네이티브 바인딩을 빌드하고, 로컬 기본값을 설정하세요:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives`용 `.node` 바이너리는 gitignore되어 있으며 모든 CLI 호출(`install:defaults`, `dev:link`, 테스트) 전에 필요합니다.\n\n### Canonical: build and link the dev `skc`\n\n전역 `skc` 명령이 **이 체크아웃의 TypeScript 소스**(모든 편집에 즉시 반영되며, 스킬/네이티브가 작동함)를 실행하도록 하려면, `PATH`에 링크하세요:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link`는 `skc` → `packages/coding-agent/src/cli.ts`를 `~/.local/bin`에 심볼릭 링크하고(`SKC_DEV_LINK_DIR`로 재정의 가능), 그 관리되는 대상을 교체하며, 다른 `skc`가 여전히 `PATH`에서 더 앞쪽에 있어 그것을 가린다면 경고하고 실패하며, `--smoke-test`를 실행하여 `@sayknow-cli/natives`가 로드되는지 확인합니다. 전체 부트스트랩(install + link + `setup defaults`)을 위해서는 `bun run install:dev`를 사용하세요.\n\n당신의 `skc`가 표류했는지(잘못된 소스, 또는 스킬을 로드할 수 없는 컴파일된 바이너리) 언제든지 확인하세요:\n\n```sh\nbun run dev:doctor\n```\n\n> 일상적인 개발에는 컴파일된 바이너리를 **사용하지 마세요**. `bun --cwd=packages/coding-agent run build`는 독립 실행형 `dist/skc`를 생성하지만, `bun build --compile` 바이너리는 `@sayknow-cli/natives`를 동적으로 로드할 수 없으므로 스킬이 `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`로 실패합니다. `dev:link`를 통해 소스에서 실행하면 이를 피할 수 있습니다. 릴리스를 검증할 때만 바이너리를 빌드하세요.\n\n링크 없이 소스에서 직접 CLI를 실행하세요:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\n기본 워크플로 정의는 커밋된 `.skc` 사본이 아니라 소스에 있습니다:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\n워크플로 정의 또는 리브랜드 표면 변경의 경우, 프로젝트 게이트를 실행하세요:\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\n패키지별 맵에 대해서는 [`docs/codebase-overview.md`](docs/codebase-overview.md)를 참조하세요.\n\n## Contributors\n\n기여, 버그 보고, 릴리스 검증은 GitHub Issues와 Pull Request를 통해 환영합니다.\n\n## Inspirations and lineage\n\nSayknow-CLI의 기본 TUI 정체성은 문어 가족입니다: 다크 기본값 ink-octopus, 라이트 기본값 blue-octopus, 그리고 red-octopus·glow-octopus·violet-octopus 대안. 또한 해당 도구들에서 옮겨오는 사용자들이 익숙한 모습을 얻도록 팔레트가 그 도구들에서 영감을 받은 `claude-code`, `codex`, `opencode` 마이그레이션 테마를 번들로 제공합니다. 공개 SKC 표면을 의도적으로 집중된 상태로 유지하면서, 작은 에이전트 하니스 계열에서 얻은 교훈을 바탕으로 만들어졌습니다. 역사적 출처 표기는 [`NOTICE.md`](NOTICE.md)에 보관되어 있습니다.\n\n## License\n\nMIT. [`LICENSE`](LICENSE)를 참조하세요.\n",
|
|
78
|
+
"readme/README.zh.md": "<p align=\"center\">\n <img src=\"../../assets/hero.png\" alt=\"Sayknow-CLI autonomous coding-agent hero illustration\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Sayknow-CLI</h1>\n\n<p align=\"center\">\n <strong>编码应当如思考般自然。</strong><br />\n 一个专注的编码智能体运行器,面向访谈式需求澄清、经评审的计划、tmux 原生执行与持久化验证。\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/tag/jaybeyond/Sayknow_CLI?sort=semver&label=release&style=flat-square&color=2f9bff\"></a>\n <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/jaybeyond/Sayknow_CLI?style=flat-square&color=green\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/stargazers\"><img alt=\"Stars\" src=\"https://img.shields.io/github/stars/jaybeyond/Sayknow_CLI?style=flat-square&color=f5c518\"></a>\n <a href=\"https://github.com/jaybeyond/Sayknow_CLI/issues\"><img alt=\"Issues\" src=\"https://img.shields.io/github/issues/jaybeyond/Sayknow_CLI?style=flat-square\"></a>\n <a href=\"https://bun.sh\"><img alt=\"Built with Bun\" src=\"https://img.shields.io/badge/built%20with-Bun-fbf0df?style=flat-square&logo=bun&logoColor=black\"></a>\n <a href=\"#languages\"><img alt=\"i18n\" src=\"https://img.shields.io/badge/i18n-7%20languages-2f9bff?style=flat-square\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"../../README.md\">English</a> ·\n <a href=\"README.ko.md\">한국어</a> ·\n <b>中文</b> ·\n <a href=\"README.ja.md\">日本語</a> ·\n <a href=\"README.es.md\">Español</a> ·\n <a href=\"README.fr.md\">Français</a> ·\n <a href=\"README.de.md\">Deutsch</a>\n</p>\n\n<p align=\"center\">\n <img src=\"../../assets/character.png\" alt=\"Sayknow-CLI character mascot\" width=\"320\" />\n</p>\n\n> Sayknow-CLI 是一个实验性的、处于 beta 阶段的项目。请预期会有粗糙之处,并在依赖其结果完成重要工作之前先行验证输出。\n\n## Languages\n\n界面已本地化为 **7 种语言**——English、한국어(韩语)、\n中文(简体)、日本語(日语)、Español(西班牙语)、\nFrançais(法语)以及 Deutsch(德语)。首次运行时它会自动检测你的系统区域设置;\n你可以随时在 **Settings → Appearance → Language** 中切换,或者使用例如\n`LANG=ja_JP.UTF-8 skc` 的方式启动。未翻译的字符串会回退到英文,而\n品牌/技术名称(Claude、OpenAI、MCP……)在所有语言环境中均保持原样。\n\n## What is Sayknow-CLI?\n\nSayknow-CLI(`skc`)是一个外部编码智能体框架(harness)。它从你选择的仓库或工作树(worktree)中运行,然后为智能体提供一个精简、明确的工作流界面:\n\n```text\ndeep-interview -> ralplan -> ultragoal\n └─ optional team execution when parallel tmux workers help\n```\n\n它有意不做成 Codex CLI、Claude Code、OpenCode 或 Claw Code 的隐藏插件。当你需要结构化的规划、持久化的证据、tmux 支持的工作进程或一个隔离的工作树时,就在这些工具旁边启动 `skc`。\n\n## Install\n\n```sh\nnpm install -g sayknow-cli # 或:bun install -g sayknow-cli\nskc --version\n```\n\n已内置 macOS·Linux·Windows 的预编译原生模块,无需 Rust 工具链或构建步骤。更新:`npm install -g sayknow-cli@latest` 或在终端运行 `skc update`。\n\n> 如果你之前是从源码(git clone)安装的,只需一次性切换:`rm -f ~/.local/bin/skc && npm install -g sayknow-cli`。源码/开发安装请参见[英文 README](../../README.md#install-from-source-development)。\n\n## Quick start\n\n```sh\n# Run directly in the current checkout\nskc\n\n# Use a tmux-backed leader session\nskc --tmux\n\n# Use an isolated worktree for risky or reviewable work\n# --worktree takes an optional branch-like name, not a filesystem path.\nskc --tmux --worktree my-task-branch\n\n# If you already created a worktree directory, launch from that directory instead.\ncd ../my-task-worktree && skc --tmux\n```\n\n在 SKC 会话内部,使用公共工作流界面:\n\n```text\n/skill:deep-interview clarify ambiguous requirements\n/skill:ralplan build and critique the implementation plan\nskc ultragoal create-goals --brief-file <approved-plan>\nskc ultragoal complete-goals\n```\n\n仅当协同的 tmux 工作进程能带来实质性帮助时,才加上 `skc team ...`。\n\n## Core capabilities\n\n- **先访谈,不靠猜**:`deep-interview` 把模糊的请求转化为具体的需求。\n- **先规划,再变更**:`ralplan` 在代码改动之前评审方案。\n- **带证据地执行**:`ultragoal` 跟踪目标、修订、检查以及完成证据。\n- **在有用时并行化**:`team` 为较大的任务协调 tmux 支持的工作进程。\n- **保持外部化且可评审**:从所选的仓库或工作树中运行,无需给另一个智能体运行时打补丁。\n- **提供商出故障也能继续**:默认模型受阻(缺少凭据、配额耗尽、认证或服务器错误)时,会话会换用另一个提供商的模型继续进行;`/fallback` 用于查看和编辑这条回退链。因重启或瞬时故障而中断的步骤会在同一模型上自动恢复一次。Z.AI `1113` 这类配额响应只请求一次就会切换,不会白白耗尽重试预算。\n- **长会话始终留在上下文窗口内**:压缩(compaction)之后,Codex 会从一个全新的、提供商可见的基线开始,而不是一路增长到 `context_length_exceeded`;压缩摘要的措辞也经过调整,避免被提供商拒绝。\n- **按含义查找代码**:手头没有可供 grep 的名称时,`locate` 工具能根据一句普通描述找到相应行为所在的位置。\n- **把工作交给合适的模型**:`/model` 可按角色和细分用途分配模型;子智能体任务声明 `specialty` 后,就会落到你为这类工作选定的模型上。\n- **在会话内完成交付**:`github` 和 `gitlab` 工具可以创建和查看 pull/merge request 及 CI,无需离开 SKC。\n- **证明测试确实跑在这份代码上**:`verification-receipts` 插件为每次测试运行保存一份回执(receipt),并在代码此后发生变化时告诉你。\n- **随时回到任意会话**:`alt+r` 打开恢复选择器,`ctrl+q` 继续最近一次会话,此外还有 `/star`、`/fork`、`/rename`,以及用于导入 Codex 和 Claude Code 记录的 `/import-session`。\n\n## Workflow surface\n\nSayknow-CLI 内置四项默认工作流技能:\n\n| Skill | What it does |\n| ---------------- | --------------------------------------------------------------------- |\n| `deep-interview` | 在规划或代码改动之前澄清模糊的需求。 |\n| `ralplan` | 在变更之前构建并评审实现计划。 |\n| `ultragoal` | 在执行、修订、验证与证据收集的全过程中跟踪目标。 |\n| `team` | 当并行执行值得时,协调 tmux 支持的工作进程。 |\n\n以及四个捆绑的角色智能体:\n\n| Agent | What it does |\n| ----------- | -------------------------------------------------- |\n| `executor` | 有边界的实现、修复与重构。 |\n| `architect` | 只读的架构与代码评审评估。 |\n| `planner` | 只读的排序与验收标准。 |\n| `critic` | 只读的计划评审与可执行性审查。 |\n\n没有庞杂的默认技能堆砌:SKC 通过把这一精简方法做得更好来持续改进。\n\n## Built-in tools\n\n智能体通过以下工具开展工作。标记为 *需启用* 的工具默认关闭,需在 **Settings → Tools**(或 `~/.skc/config.yml` 中列出的键)里开启。\n\n| Area | Tools |\n| ---- | ----- |\n| 文件与代码 | `read`、`write`、`edit`、`find`、`search`、`locate`(按描述查找代码)、`ast_grep` / `ast_edit`(语法感知的搜索与重写)、`lsp` |\n| Shell 与运行时 | `bash`、`eval`(JS/Python 单元)、`ssh`、`debug`、`bisect`、`calc` |\n| 委派与跟踪 | `task`(子智能体)、`subagent`、`job`、`monitor`、`cron`、`irc`(与运行中的智能体对话)、`todo_write`、`goal`、`checkpoint` / `rewind` |\n| Git 托管 | `github`(*需启用*,`github.enabled`):通过 `gh` 处理 pull request、推送和 CI 运行 · `gitlab`(*需启用*,`gitlab.enabled`,需要 [`glab`](https://gitlab.com/gitlab-org/cli)):`mr_create`(若已有打开的 MR 则直接返回,不会重复创建)、`mr_view`、`mr_list`、`ci_status`,支持 gitlab.com 和自托管实例 |\n| 网页与设备 | `web_search`、`browser`、`computer`、`render_mermaid` |\n| 发现 | `search_tool_bm25`(按需激活隐藏工具和 MCP 工具)、`skill`、`skill_discovery`、`ask` |\n\n用 `--tools read,bash,...` 为单次运行指定工具集;插件、自定义和 MCP 工具的名称同样可以写在这里。\n\n## Plugins\n\nSKC 会加载插件包(工具、hook、技能、MCP 服务器):安装时校验哈希,之后一旦有文件被改动,该插件包就会被隔离。使用 `skc plugin install|list|...` 管理插件。\n\n**`verification-receipts`**(随本仓库提供)回答的问题是“测试真的在当前这份代码上通过了吗?”:\n\n- `verification_run` 使用 `bun test` 或 `node --test` 运行明确指定的测试文件,并保存一份不可变的回执:每个文件的通过/失败计数,外加工作树的指纹。\n- `verification_status` 无需重跑测试即可重新计算该指纹,并报告 `fresh`;代码一旦改动则报告 `stale`。\n- `verification_loop` 及其 hook 会在后台 `task` 已结束、却没有 fresh 回执时提醒你。\n\n它仅供参考(advisory),只支持 POSIX,且 `node --test` 需要 Node 24.11.1+。它不包含在 npm 包中,请从源码检出中安装:\n\n```sh\ngit clone https://github.com/jaybeyond/Sayknow_CLI.git\nskc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user\n```\n\n## Works beside your existing agent or bot\n\n| Tool or bot | Recommended SKC command | Boundary |\n| ----------- | ----------------------- | -------- |\n| Codex CLI | `skc --tmux --worktree <name>` or `skc` | `--worktree` 指定一个由 SKC 管理的同级工作树;对于已存在的路径,请先 `cd` 到那里。 |\n| Claude Code | `skc --tmux` or `skc --tmux --worktree <name>` | SKC 不会成为 Claude Code 的扩展。 |\n| OpenCode | `skc` or `skc --tmux` | 目前仅支持外部运行器(external-runner)工作流。 |\n| Claw Code | `skc --tmux --worktree <name>` | SKC 不会安装到 Claw Code 中,也不会替代它。 |\n| External controller / bot | `skc mcp-serve coordinator` plus `skc setup hermes` for compatible config, or `skc --mode rpc` for a subprocess worker | 任何具备 MCP/RPC 能力的 bot 都通过通用的 coordinator/RPC 契约来驱动 SKC,而非抓取滚动回显(scrollback scraping)。 |\n\n关于通用第三方 bot 的设置以及与提供商无关的冒烟测试,请参阅 [`docs/bot-integration.md`](docs/bot-integration.md)。关于在 MCP、RPC、ACP 与 Bridge/HTTPS 各界面上的就绪度分级,请参阅 [`docs/external-control-readiness.md`](docs/external-control-readiness.md)。关于更底层的协议细节,请参阅 [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md)、[`docs/rpc.md`](docs/rpc.md) 以及 [`docs/bridge.md`](docs/bridge.md)。关于远程操作员界面的路线图,请参阅 [`docs/sayknow-remote.md`](docs/sayknow-remote.md)(网页方向盘)以及 [`docs/telegram-remote.md`](docs/telegram-remote.md)(Telegram 生命周期按钮)。\n\n## Configuration\n\n提供商的重试、恢复与回退行为位于 `~/.skc/config.yml`(以下为默认值):\n\n```yaml\nretry:\n requestMaxRetries: 4\n streamMaxRetries: 100\n maxRetries: 3\n maxDelayMs: 300000\n autoResume: true # 中断的步骤在同一模型上自动恢复一次\n maxSilentTimeouts: 3 # 连续出现这么多次无输出超时后停止\nfallback:\n auto: true # 默认模型受阻时,换用另一个已登录的提供商继续\n maxAttempts: 3 # 链中每个模型的尝试次数,用完后切换到下一个\n```\n\n`requestMaxRetries` 在流(stream)建立之前生效。`streamMaxRetries` 仅适用于可安全重放的瞬时流失败。无效的认证、不受支持的模型/提供商、格式错误的请求、上下文溢出、用户中止以及永久性配额失败会在当前模型上快速失败(fail-fast);启用 `fallback.auto` 时,受阻的默认模型随后会交接给链中的下一个模型(`/fallback` 可查看和编辑这条链)。\n\n## TUI identity\n\n默认的 TUI 标识是 SKC 的 **ink-octopus**(章鱼墨汁)主题——温暖的石墨色、纸色文字、唯一的琥珀色强调——用于深色终端,浅色终端使用 **blue-octopus**(蓝章鱼)。还捆绑了一个暖色调的 **red-octopus**(红章鱼)变体,供偏好更深、高对比度配色的用户使用。另有三个迁移主题——`claude-code`、`codex` 和 `opencode`——分别复刻了这些工具的外观,以便于视觉迁移,可从 Settings 或 `/theme` 中选择。显式的用户主题设置仍然优先生效。\n\n### Bundled theme grid\n\n从 Settings(`Appearance -> Dark theme` / `Light theme`)或 `/theme` 中选择。\n\n| Theme | Visual feel | Best fit |\n| --- | --- | --- |\n| `blue-octopus` | 蓝章鱼配色,带触手蓝点缀。 | 浅色终端的默认主题。 |\n| `red-octopus` | 暖色调红章鱼变体,状态对比强烈。 | 高对比度的深色替代方案。 |\n| `ink-octopus` | 章鱼墨汁 — 温暖的石墨色背景、纸色文字、唯一的琥珀色强调。 | 深色终端的默认主题。 |\n| `glow-octopus` | 深海生物荧光 — 青黑底色配荧光绿,辅以紫色。 | 需要鲜明强调色的深色终端。 |\n| `violet-octopus` | 梅紫色深色底配薰衣草强调,辅以杏色。 | 柔和多彩的深色备选。 |\n| `claude-code` | 受 Claude Code 启发的深色配色,带赤陶色和粉色高光。 | 在不离开 SKC 的情况下保留 Claude Code 的肌肉记忆。 |\n| `codex` | 清爽的深蓝灰配色,编码会话对比更锐利。 | 类似 Codex 的深色工作区。 |\n| `opencode` | 受 OpenCode 启发的深色配色,终端点缀更鲜明。 | 在捆绑选择器中保留 OpenCode 的肌肉记忆。 |\n\n## Development\n\n安装依赖、构建原生绑定,并设置本地默认值:\n\n```sh\nbun install\nbun run build:native\nbun run install:defaults\n```\n\n`@sayknow-cli/natives` 的 `.node` 二进制文件已被 gitignore,且在任何 CLI 调用(`install:defaults`、`dev:link`、测试)之前都是必需的。\n\n### Canonical: build and link the dev `skc`\n\n要让全局 `skc` 命令运行**此检出的 TypeScript 源码**(对每一次编辑都即时生效,且技能/原生绑定均可用),请把它链接到你的 `PATH`:\n\n```sh\nbun install\nbun run dev:link\n```\n\n`dev:link` 会把 `skc` → `packages/coding-agent/src/cli.ts` 软链接到 `~/.local/bin`(可用 `SKC_DEV_LINK_DIR` 覆盖),替换该受管目标,如果另一个 `skc` 仍在 `PATH` 上更靠前地遮蔽它则会发出警告并失败,并运行 `--smoke-test` 以确认 `@sayknow-cli/natives` 能够加载。使用 `bun run install:dev` 进行完整的引导(install + link + `setup defaults`)。\n\n随时检查你的 `skc` 是否已经漂移(源码错误,或一个无法加载技能的已编译二进制文件):\n\n```sh\nbun run dev:doctor\n```\n\n> 在日常开发中**不要**使用已编译的二进制文件。`bun --cwd=packages/coding-agent run build` 会产出一个独立的 `dist/skc`,但 `bun build --compile` 生成的二进制无法动态加载 `@sayknow-cli/natives`,因此技能会以 `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` 失败。通过 `dev:link` 从源码运行可避免此问题。仅在验证发布版本时才构建该二进制文件。\n\n不进行链接,直接从源码运行 CLI:\n\n```sh\nbun packages/coding-agent/src/cli.ts --help\n```\n\n默认工作流定义存放在源码中,而非已提交的 `.skc` 副本:\n\n```text\npackages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md\npackages/coding-agent/src/prompts/agents/<role>.md\n```\n\n对于工作流定义或品牌重塑界面(rebrand-surface)的改动,请运行项目门禁(gates):\n\n```sh\nbun scripts/check-visible-definitions.ts\nbun scripts/verify-g002-gates.ts\nbun scripts/rebrand-inventory.ts --strict\nbun test packages/coding-agent/test/default-skc-definitions.test.ts\n```\n\n关于逐包(package-by-package)的对照图,请参阅 [`docs/codebase-overview.md`](docs/codebase-overview.md)。\n\n## Contributors\n\n欢迎通过 GitHub Issues 和 Pull Requests 进行贡献、提交错误报告以及参与发布验证。\n\n## Inspirations and lineage\n\nSayknow-CLI 默认的 TUI 标识是章鱼家族:深色默认 ink-octopus,浅色默认 blue-octopus,以及 red-octopus、glow-octopus、violet-octopus 备选。它还捆绑了 `claude-code`、`codex` 和 `opencode` 迁移主题,其配色受这些工具启发,以便从它们迁移过来的用户能获得熟悉的外观。它在一个小型智能体框架家族的经验之上构建,同时有意保持公共 SKC 界面的专注。历史归属保留在 [`NOTICE.md`](NOTICE.md) 中。\n\n## License\n\nMIT。参见 [`LICENSE`](LICENSE)。\n",
|
|
78
79
|
"render-mermaid.md": "# RenderMermaid\n\n`RenderMermaid` is an optional built-in tool that renders Mermaid source to terminal-friendly text.\n\n## Enable it\n\nDisabled by default. Turn it on in `/settings` under **Tools → Render Mermaid**, or in `~/.skc/agent/config.yml`:\n\n```yaml\nrenderMermaid:\n enabled: true\n```\n\n## What it does\n\n- Tool name: `render_mermaid`\n- Input: Mermaid source in the required `mermaid` field\n- Output: rendered ASCII/Unicode text, not SVG or PNG\n- Storage: when artifact storage is available, the full render is also saved as an `artifact://...`\n\nThere are no model-specific or environment-variable prerequisites. Once enabled, any model that can call built-in tools can use it.\n\n## Parameters\n\n```json\n{\n \"mermaid\": \"graph TD\\n A[Start] --> B[Stop]\",\n \"config\": {\n \"useAscii\": false,\n \"paddingX\": 2,\n \"paddingY\": 2,\n \"boxBorderPadding\": 0\n }\n}\n```\n\nAvailable `config` fields:\n\n- `useAscii` — `true` for plain ASCII, `false` for Unicode box-drawing characters (default and usually more readable)\n- `paddingX` — horizontal spacing between nodes\n- `paddingY` — vertical spacing between nodes\n- `boxBorderPadding` — inner padding inside node boxes\n\n## Current limitations\n\n`RenderMermaid` uses the `beautiful-mermaid` ASCII renderer. It works best for flowcharts and small diagrams.\n\nComplex sequence diagrams, especially with `alt` / `else` blocks, can become very wide in a terminal. That is current renderer behavior, not a provider or model configuration problem.\n\nIf a sequence diagram is hard to read:\n\n1. Keep Unicode output (`useAscii: false`)\n2. Reduce spacing with a tighter config such as `paddingX: 2`, `paddingY: 2`, `boxBorderPadding: 0`\n3. Prefer smaller sub-diagrams over one large sequence diagram\n4. Open the saved artifact if the inline preview is truncated in the TUI\n\n## Example\n\nInput:\n\n```mermaid\ngraph TD\n A[Start] --> B{Decision}\n B -->|Yes| C[Action]\n B -->|No| D[End]\n```\n\nTypical result:\n\n```text\n┌─────┐\n│Start│\n└─────┘\n │\n ▼\n┌────────┐\n│Decision│\n└────────┘\n```\n",
|
|
79
80
|
"research-plan-ledger.md": "# Research plan items and evidence ledger\n\nResearch/deep-research workflows need a planning contract that is stronger than an execution-order checklist. A plan item should name the claim under investigation, the uncertainty around it, what evidence is required, what counterexamples would falsify it, and how a verifier should handle source conflicts.\n\nThis document defines the public product-facing spike for issue #932. It intentionally avoids private operator, session, channel, and routing internals.\n\n## Research plan item schema\n\n```ts\ntype ResearchPlanConfidence = \"low\" | \"medium\" | \"high\";\n\ntype ResearchPlanItem = {\n claim: string;\n confidence: ResearchPlanConfidence;\n unknowns: string[];\n evidenceNeeded: string[];\n counterexampleQueries: string[];\n sourceConflictPolicy: string;\n dropCondition: string;\n verifierChecks: string[];\n};\n```\n\nField intent:\n\n- `claim`: The smallest claim that can survive or fail verification.\n- `confidence`: Planner's initial confidence before evidence collection.\n- `unknowns`: Known gaps the final answer must resolve or explicitly carry forward.\n- `evidenceNeeded`: Evidence workers must collect before the claim can be accepted.\n- `counterexampleQueries`: Directed search prompts for evidence that would weaken or falsify the claim.\n- `sourceConflictPolicy`: How the verifier treats conflicting sources, stale sources, or mismatched methodology.\n- `dropCondition`: The explicit condition that removes this claim from the final answer.\n- `verifierChecks`: Checklist the verifier applies before accepting the claim.\n\n## Evidence ledger schema\n\n```ts\ntype ResearchEvidenceVerdict = \"support\" | \"contradict\" | \"uncertain\";\n\ntype ResearchEvidenceEntry = {\n claim: string;\n source: string;\n confidence: ResearchPlanConfidence;\n verdict: ResearchEvidenceVerdict;\n notes?: string;\n};\n\ntype ResearchLedgerVerdict = {\n claim: string;\n finalVerdict: \"accepted\" | \"rejected\" | \"uncertain\";\n survivingSources: ResearchEvidenceEntry[];\n rejectReason?: string;\n unresolvedUnknowns: string[];\n};\n```\n\nThe ledger is claim-centric. Workers add evidence entries against plan-item claims; the verifier reduces those entries into a final verdict. Accepted claims can be cited in the final answer. Rejected claims are named with `rejectReason`. Uncertain claims are either excluded or marked explicitly as unresolved.\n\n## Ralplan/research workflow shape\n\n1. Planner emits `ResearchPlanItem[]` alongside the normal plan narrative when the task is research-heavy.\n2. Workers gather independent evidence for each item, including counterexample-oriented searches.\n3. Verifier checks contradictions, source quality, stale information, and unresolved uncertainty using the item's `verifierChecks`, `sourceConflictPolicy`, and `dropCondition`.\n4. The final answer cites accepted claims, lists rejected claims with reasons, and marks any surviving uncertainty.\n\n## Example\n\n```ts\nconst item: ResearchPlanItem = {\n claim: \"Model X reduces latency by 30% on production-like workloads\",\n confidence: \"medium\",\n unknowns: [\"production workload mix\"],\n evidenceNeeded: [\"benchmark with production-like fixture\", \"baseline comparison\"],\n counterexampleQueries: [\"regression on long-context workload\", \"cold-start latency increase\"],\n sourceConflictPolicy: \"Reject the claim when any credible counterexample contradicts the benchmark.\",\n dropCondition: \"Drop if a counterexample contradicts the claim or key unknowns remain unresolved.\",\n verifierChecks: [\"check source freshness\", \"compare benchmark harness\", \"inspect counterexample evidence\"],\n};\n```\n\nIf the ledger contains a supporting benchmark and a credible long-context counterexample, the verifier rejects the broad claim instead of letting a plausible summary survive by vibes.\n\n## Current spike\n\nThe first implementation spike lives in `packages/coding-agent/src/research-plan/ledger.ts` and provides:\n\n- TypeScript interfaces for research plan items, evidence entries, and final verdicts.\n- Validators for product-facing plan/evidence objects.\n- A deterministic verifier helper that rejects plausible claims when counterexample/source-conflict/drop-condition evidence applies.\n- Regression tests in `packages/coding-agent/test/research-plan-ledger.test.ts`.\n\nFuture runtime integration can make `/skill:ralplan` emit these structures as a fenced JSON block or structured sidecar in the persisted ralplan artifact. The spike keeps the schema independent from private session state so it can be exposed in docs and tests safely.\n",
|
|
80
81
|
"resolve-tool-runtime.md": "# Resolve tool runtime internals\n\nThis document explains how preview/apply workflows are modeled in coding-agent and how built-in or custom tools can participate via the tool-choice queue and `pushPendingAction`.\n\n## Scope and key files\n\n- [`src/tools/resolve.ts`](../packages/coding-agent/src/tools/resolve.ts)\n- [`src/tools/ast-edit.ts`](../packages/coding-agent/src/tools/ast-edit.ts)\n- [`src/extensibility/custom-tools/types.ts`](../packages/coding-agent/src/extensibility/custom-tools/types.ts)\n- [`src/extensibility/custom-tools/loader.ts`](../packages/coding-agent/src/extensibility/custom-tools/loader.ts)\n- [`src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n\n## What `resolve` does\n\n`resolve` is a hidden tool that finalizes a pending preview action.\n\n- `action: \"apply\"` executes the queued action's `apply(reason)` callback and returns that result with resolve metadata.\n- `action: \"discard\"` invokes `reject(reason)` if provided; otherwise returns `Discarded: <label>. Reason: <reason>`.\n\nIf no pending action exists, `resolve` fails with:\n\n- `No pending action to resolve. Nothing to apply or discard.`\n\n## Pending actions use the tool-choice queue\n\nPreview producers call `queueResolveHandler(...)`, which pushes a one-shot forced `resolve` directive onto the session tool-choice queue and adds a `resolve-reminder` steering message.\n\nRuntime behavior:\n\n- the queued handler owns the pending `apply`/`reject` callbacks,\n- `resolve` looks up the current queue invoker with `session.peekQueueInvoker()`,\n- if the model rejects the forced tool choice, the queue directive is requeued,\n- `resolve` does not maintain a separate pending-action stack.\n\nMultiple pending previews therefore follow the active tool-choice queue ordering, not an independent pending-action store.\n\n## Built-in producer example (`ast_edit`)\n\n`ast_edit` previews structural replacements first. When the preview has replacements and is not applied yet, it queues a resolve handler that contains:\n\n- label (human-readable summary)\n- `sourceToolName` (`ast_edit`)\n- `apply(reason: string)` callback that reruns AST edit with `dryRun: false`\n\n`resolve(action=\"apply\", reason=\"...\")` passes `reason` into this callback.\n\n## Custom tools: `pushPendingAction`\n\nCustom tools can register resolve-compatible pending actions through `CustomToolAPI.pushPendingAction(...)`. The custom tool loader forwards these actions to `queueResolveHandler(...)` when that hook is available.\n\n`CustomToolPendingAction`:\n\n- `label: string` (required)\n- `apply(reason: string): Promise<AgentToolResult<unknown>>` (required) — invoked on apply; `reason` is the string passed to `resolve`\n- `reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>` (optional) — invoked on discard; return value replaces the default \"Discarded\" message if provided\n- `details?: unknown` exists on the public custom-tool type but is not currently forwarded by the loader into resolve metadata\n- `sourceToolName?: string` (optional, defaults to `\"custom_tool\"`)\n\n### Minimal usage example\n\n```ts\nimport type { CustomToolFactory } from \"@sayknow-cli/coding-agent\";\n\nconst factory: CustomToolFactory = (pi) => ({\n name: \"batch_rename_preview\",\n label: \"Batch Rename Preview\",\n description: \"Previews renames and defers commit to resolve\",\n parameters: pi.zod.object({\n files: pi.zod.array(pi.zod.string()),\n }),\n\n async execute(_toolCallId, params) {\n const previewSummary = `Prepared rename plan for ${params.files.length} files`;\n\n pi.pushPendingAction({\n label: `Batch rename: ${params.files.length} files`,\n sourceToolName: \"batch_rename_preview\",\n apply: async (reason) => {\n // apply writes here\n return {\n content: [\n { type: \"text\", text: `Applied batch rename. Reason: ${reason}` },\n ],\n };\n },\n reject: async (reason) => {\n // optional: cleanup or notify on discard\n return {\n content: [\n { type: \"text\", text: `Discarded batch rename. Reason: ${reason}` },\n ],\n };\n },\n });\n\n return {\n content: [\n {\n type: \"text\",\n text: `${previewSummary}. Call resolve to apply or discard.`,\n },\n ],\n };\n },\n});\n\nexport default factory;\n```\n\n## Runtime availability and failures\n\n`pushPendingAction` is wired by the custom tool loader through the active session's resolve queue hook.\n\nIf the runtime did not provide the resolve queue hook, `pushPendingAction` throws:\n\n- `Pending action store unavailable for custom tools in this runtime.`\n\n## Tool-choice behavior\n\nWhen `queueResolveHandler(...)` registers a preview, the agent runtime forces a one-shot `resolve` tool choice so pending previews are explicitly finalized before normal tool flow continues.\n\n## Developer guidance\n\n- Use pending actions only for destructive or high-impact operations that should support explicit apply/discard.\n- Keep `label` concise and specific; it is shown in resolve renderer output.\n- Ensure `apply(reason)` is deterministic and idempotent enough for one-shot execution; `reason` is informational and should not change behavior.\n- Implement `reject(reason)` when the discard needs cleanup (temp state, locks, notifications); omit it for stateless previews where the default message suffices.\n- If your tool can stage multiple previews, remember they are mediated by the tool-choice queue rather than a separate pending-action stack.\n",
|
|
@@ -115,6 +116,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
|
|
|
115
116
|
"tools/eval.md": "# eval\n\n> Execute Python or JavaScript code in persistent cell-based runtimes.\n\n> **Notice:** Do not shell out to `python -c`/`python -e`, `bun -e`, or `node -e` via the `bash` tool for ad-hoc code execution. Use this tool instead — it gives you persistent state across cells, structured `display()` output, image/JSON capture, and proper cancellation/timeout handling that one-shot `-e`/`-c` invocations cannot provide.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/eval.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/eval.md`\n- Key collaborators:\n - `packages/coding-agent/src/eval/backend.ts` — backend execution contract\n - `packages/coding-agent/src/eval/js/index.ts` — JS backend adapter\n - `packages/coding-agent/src/eval/js/executor.ts` — JS execution + output sink\n - `packages/coding-agent/src/eval/js/context-manager.ts` — persistent VM contexts, prelude, tool bridge\n - `packages/coding-agent/src/eval/js/prelude.txt` — JS global helpers\n - `packages/coding-agent/src/eval/py/index.ts` — Python backend adapter\n - `packages/coding-agent/src/eval/py/executor.ts` — kernel session retention, reset, cleanup\n - `packages/coding-agent/src/eval/py/kernel.ts` — Jupyter gateway/kernel protocol, display capture\n - `packages/coding-agent/src/eval/py/prelude.py` — Python helper functions and status events\n - `packages/coding-agent/src/session/streaming-output.ts` — truncation, artifacts, streamed chunks\n - `docs/python-repl.md` — Python kernel/gateway internals\n\n## Inputs\n\nTool parameters are a JSON object with a single `cells` field — an ordered array of cell objects. Each cell is a structured record; there is no `*** Cell` header parsing, no language sniffing, and no implicit single-cell fallback. Cells run in array order; state persists within each language across cells and across tool calls.\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `cells` | `EvalCellInput[]` | Yes | Cells executed in order. At least one cell is required (`.min(1)`). |\n\nEach `EvalCellInput` (from `evalCellSchema` in `packages/coding-agent/src/tools/eval.ts`):\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `language` | `\"py\" \\| \"js\"` | Yes | Backend selector. `\"py\"` maps to the IPython/Jupyter kernel (`python` backend); `\"js\"` maps to the persistent JavaScript VM. |\n| `code` | `string` | Yes | Cell body, verbatim. JSON-encoded — embed newlines, quotes, and indentation directly; no fences, no headers. |\n| `title` | `string` | No | Short label rendered in the transcript (e.g. `\"imports\"`, `\"load config\"`). |\n| `timeout` | `integer` | No | Per-cell timeout in seconds, clamped to `1..600`. Defaults to 30 when omitted. |\n| `reset` | `boolean` | No | Wipe this cell's language kernel before running. Reset is per-language: a `py` cell's reset does not touch the JS VM and vice versa. Defaults to `false`. |\n\nMinimal example matching the live schema:\n\n```json\n{\n \"cells\": [\n { \"language\": \"py\", \"title\": \"imports\", \"timeout\": 10, \"code\": \"import json\\nfrom pathlib import Path\" },\n { \"language\": \"py\", \"title\": \"load config\", \"code\": \"data = json.loads(read('package.json'))\\ndisplay(data)\" },\n { \"language\": \"js\", \"title\": \"summary\", \"reset\": true, \"code\": \"const data = JSON.parse(await read('package.json'));\\ndisplay(data);\\nreturn data.name;\" }\n ]\n}\n```\n\n## Outputs\n\nFinal result from `EvalTool.execute()` is single-shot, but `onUpdate` streams partial text and `details` while cells run.\n\nReturned shape:\n\n- `content`: one text block containing combined cell output, or `(no text output)` / `(no output)` when only rich outputs exist.\n- `details` (`EvalToolDetails` from `packages/coding-agent/src/eval/types.ts`):\n - `cells`: per-cell code, status (`pending`/`running`/`complete`/`error`), output, duration, exit code, status events, markdown flag\n - `language`: first backend used\n - `languages`: distinct backends used, in first-use order\n - `jsonOutputs`: structured values emitted via `display(...)`\n - `images`: image payloads emitted by Python rich display or JS `display({ type: \"image\", ... })`\n - `statusEvents`: aggregated helper/tool status events\n - `notice`: backend fallback notice (currently unused; reserved for future per-cell notices)\n - `meta`: truncation metadata\n - `isError`: set on cell failure or cancellation\n\nRenderer behavior in `packages/coding-agent/src/tools/eval.ts`:\n\n- call preview renders each cell's `code` with syntax highlighting based on its declared `language`\n- result view renders each cell separately, including status, duration, and output\n- markdown outputs are rendered with the Markdown component instead of plain text\n- `jsonOutputs` render as a tree, collapsed or expanded depending on UI state\n- timeout / truncation notices render as dim metadata lines\n- images are carried in `details.images`; generic tool UI image handling renders them outside the text block\n\nSide-channel artifacts:\n\n- `session.allocateOutputArtifact?.(\"eval\")` may allocate an `artifact://...` backing store for spilled output.\n- Truncated output metadata points at that artifact when available.\n\n## Flow\n\n1. `EvalTool.execute()` in `packages/coding-agent/src/tools/eval.ts` receives `params.cells` already validated by the Zod schema — no string parsing step.\n2. For each cell, `execute()` maps `cell.language` to an `EvalLanguage` (`\"py\"` → `\"python\"`, `\"js\"` → `\"js\"`) and calls `resolveBackend(session, language)`:\n - `python` is gated on `eval.py !== false` and `pythonBackend.isAvailable(session)`.\n - `js` is gated on `eval.js !== false`.\n - A disabled or unavailable requested backend throws `ToolError`; there is no auto-fallback or sniffing.\n3. The tool allocates an `OutputSink`, a `TailBuffer`, per-cell result objects, and a `sessionAbortController`. `session.trackEvalExecution?.(...)` can wrap the whole run for external cancellation tracking.\n4. Cells execute sequentially. For each cell, `execute()`:\n - clamps `(cell.timeout ?? 30) * 1000` ms through `clampTimeout(\"eval\", ...)`\n - builds a combined abort signal from the tool signal, the timeout, and the session abort controller\n - marks the cell `running` and emits an update\n - calls the backend’s `execute()` with `cwd`, `sessionId`, `sessionFile`, `kernelOwnerId`, `deadlineMs`, `reset` (defaults to `false`), artifact info, and chunk callback\n5. JS cells dispatch through `packages/coding-agent/src/eval/js/index.ts` into `executeJs()`; Python cells dispatch through `packages/coding-agent/src/eval/py/index.ts` into `executePython()`.\n6. Backend text chunks stream into the shared `OutputSink`; rich outputs are accumulated separately as JSON, images, markdown markers, and status events.\n7. After each cell:\n - text output is trimmed and stored on that cell result\n - multi-cell runs prefix text with `[i/n]` and the optional title\n - cancellations return early with `isError: true` and a cell-specific abort message\n - non-zero exit codes return early with `isError: true` and a message naming the failed cell\n - later cells are skipped after the first error, but earlier cell state persists in the underlying runtime\n8. On success, the tool joins all cell outputs, synthesizes `(no text output)` or `(no output)` when needed, and attaches truncation metadata from `summarizeFinal()`.\n9. The renderer uses `details.cells`, `details.jsonOutputs`, and `details.statusEvents` to build notebook-style output. `mergeCallAndResult = true` and `inline = true`, so call and result render together in the transcript.\n\n## Modes / Variants\n\n### Backend selection\n\nBackend choice is **explicit per cell** — there is no auto-detection.\n\n- `language: \"py\"` → Python (IPython/Jupyter) backend\n- `language: \"js\"` → JavaScript VM backend\n\nIf the requested backend is disabled or unavailable, the tool throws `ToolError` for that cell. The caller chooses; the tool does not silently substitute.\n\n### JavaScript runtime\n\nImplemented in `packages/coding-agent/src/eval/js/context-manager.ts` and `packages/coding-agent/src/eval/js/prelude.txt`.\n\n- Persistent `vm.Context` instances keyed by `js:${sessionId}` in `vmContexts`\n- `reset: true` calls `resetVmContext(sessionKey)` before the cell executes\n- Top-level `await` and bare `return` are supported by wrapping code in an async IIFE when `wrapCode()` sees `await` or `return`\n- Top-level static `import ... from ...` and dynamic `import(...)` calls are routed through `rewriteImports()`, which sends them via `__skc_import__` so the specifier resolves against the session cwd\n- Module cache is busted for **local** imports between cells so edits to source files are picked up without restarting the runtime. `__skc_import__` deletes `require.cache[absPath]` before re-importing whenever the original specifier is a filesystem path: relative (`./x`, `../x`, `.`, `..`), POSIX-absolute (`/...`), home-prefixed (`~/...`), or Windows drive-letter (`C:\\...` / `C:/...`). Bare specifiers (`react`, `lodash/x`) and URL/scheme specifiers (`node:fs`, `file://...`, `https://...`) are left in cache so package identity stays stable across cells. The cache-bust only fires when the resolved target is an absolute path — unresolved bare-package fallbacks (`resolveImportSpecifier()` returning the original specifier) skip it.\n- The prelude installs globals:\n - `display`, `print`\n - `read`, `write`, `append`, `sort`, `uniq`, `counter`, `diff`, `tree`, `env`, `output`\n - `tool.<name>(args)` proxy for arbitrary session tool calls\n- JS helpers are async because they cross the VM/tool boundary\n- `display(value)` behavior:\n - plain objects/arrays become JSON outputs\n - `{ type: \"image\", data, mimeType }` becomes an image output\n - scalars become text\n- The VM exposes a restricted `process` subset plus `Buffer`, `fetch`, `Blob`, `File`, `Headers`, `Request`, `Response`, `fs`, `require`, and browser-style globals\n- Per-session VM runs are serialized with `runQueued()`\n\n### Python runtime\n\nImplemented in `packages/coding-agent/src/eval/py/executor.ts`, `packages/coding-agent/src/eval/py/kernel.ts`, and `packages/coding-agent/src/eval/py/prelude.py`. See `docs/python-repl.md` for gateway and kernel details.\n\n- Default mode is retained `session` kernels keyed by `python:${sessionId}`\n- Optional `python.kernelMode = \"per-call\"` creates a fresh kernel for each cell and shuts it down afterward\n- `reset: true` disposes the retained kernel for that session before the cell runs; later Python cells in the same tool call reuse the fresh kernel\n- Startup path:\n - availability check\n - create/connect kernel\n - initialize cwd / env / `sys.path`\n - execute `PYTHON_PRELUDE`\n- Python cells run inside IPython/Jupyter, so top-level `await` works; the prompt warns not to use `asyncio.run(...)`\n- The Python prelude defines synchronous helpers with the same surface as JS (except `tool.<name>` exists only in JS)\n- `display(value)` wraps dict/list/tuple values in `IPython.display.JSON`; rich display MIME bundles are preserved\n- Kernel `display_data` / `execute_result` messages map to:\n - `application/x-skc-status` → status event\n - `image/png` → image output\n - `application/json` → JSON output\n - `text/markdown` → markdown output\n - `text/plain` → text output\n - `text/html` → HTML converted to markdown with `htmlToBasicMarkdown()`\n- Interactive stdin is rejected: `input_request` sends an empty reply, marks `stdinRequested`, and the executor returns exit code `1`\n\n### Multi-language call behavior\n\nA single tool call can mix Python and JS cells. Persistence is per language runtime:\n\n- `reset: true` on a Python cell does not touch JS state\n- `reset: true` on a JS cell does not touch Python state\n- each backend keeps its own retained session keyed from the same session-derived ID\n\n## Side Effects\n\n- Filesystem\n - JS/Python prelude helpers can read, write, append, diff, and traverse files under the session cwd or absolute paths.\n - Output may spill to an artifact file via `OutputSink`.\n- Network\n - Python backend speaks NDJSON to a local `python3` subprocess over stdin/stdout (no network).\n - JS runtime exposes `fetch` and `tool.<name>()`; those tools may perform additional network I/O.\n- Subprocesses / native bindings\n - Python availability check runs `<python> -c ...`.\n - Python backend spawns one `python -u runner.py` subprocess per kernel; cancellation sends `SIGINT`. Details in `docs/python-repl.md`.\n- Session state\n - `session.assertEvalExecutionAllowed?.()` can block execution.\n - `session.trackEvalExecution?.(...)` can register cancellable eval work.\n - `session.getSessionFile?.()` and `session.getEvalKernelOwnerId?.()` influence kernel reuse and artifact lookup.\n - JS VM contexts persist in `vmContexts` across eval calls until reset/disposal.\n - Python retained kernels persist in `kernelSessions` until reset, eviction, idle cleanup, or owner cleanup.\n- User-visible prompts / interactive UI\n - none; stdin requests are rejected programmatically\n- Background work / cancellation\n - Python retained kernels have heartbeat and idle cleanup timers.\n - Cancellation interrupts a running Python kernel and aborts JS promise waits.\n\n## Limits & Caps\n\n- Per-cell timeout default: 30s (applied when `timeout` is omitted in `EvalTool.execute()`; clamped through `TOOL_TIMEOUTS.eval.default` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Schema-level `timeout` range: integer `1..600` seconds (enforced by Zod on the cell schema)\n- Timeout clamp at runtime: 1s minimum, 600s maximum (`TOOL_TIMEOUTS.eval` in `packages/coding-agent/src/tools/tool-timeouts.ts`)\n- Transcript code/output preview: 10 lines by default (`EVAL_DEFAULT_PREVIEW_LINES` in `packages/coding-agent/src/tools/eval.ts`)\n- Output truncation window: 50KB default (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Output line cap inside truncation helpers: 3000 lines (`DEFAULT_MAX_LINES` in `packages/coding-agent/src/session/streaming-output.ts`)\n- Streaming tail buffer for live updates: `DEFAULT_MAX_BYTES * 2` = 100KB (`packages/coding-agent/src/tools/eval.ts`)\n- Python retained kernel idle timeout: 5 minutes (`IDLE_TIMEOUT_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python retained kernel cap: 4 sessions (`MAX_KERNEL_SESSIONS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python retained kernel cleanup sweep: every 30s (`CLEANUP_INTERVAL_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python owner-cleanup shutdown wait: 2000ms (`OWNER_CLEANUP_KERNEL_SHUTDOWN_TIMEOUT_MS` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python heartbeat interval: 5s (`ensureKernelHeartbeat()` in `packages/coding-agent/src/eval/py/executor.ts`)\n- Python external gateway availability check timeout: 5s (`AbortSignal.timeout(5000)` in `packages/coding-agent/src/eval/py/kernel.ts`)\n- Python auto-restart budget: one restart per retained session before hard failure (`restartCount > 1` in `packages/coding-agent/src/eval/py/executor.ts`)\n\n## Errors\n\n- Zod validation rejects malformed `cells` arrays before `execute()` runs (missing `language`/`code`, out-of-range `timeout`, empty `cells`).\n- Missing session without proxy executor throws `ToolError(\"Eval tool requires a session when not using proxy executor\")`.\n- Disabled/unavailable backends throw `ToolError` from `resolveBackend()`:\n - `eval.py = false` and a `py` cell is requested\n - `eval.js = false` and a `js` cell is requested\n - Python kernel unavailable and a `py` cell is requested\n- JS runtime exceptions are converted into text output plus `exitCode: 1`; cancellations return `cancelled: true` and may append `Command timed out`.\n- Python execution errors from the kernel become text output and `exitCode: 1`; later cells are skipped.\n- Python stdin requests are treated as errors with the message `Kernel requested stdin; interactive input is not supported.`\n- Cancellation is returned, not thrown, once backend execution has started. The tool formats it as a cell failure and sets `details.isError = true`.\n- If output truncates, the tool still succeeds; truncation is surfaced through `details.meta` and artifact-backed full output when available.\n\n## Notes\n\n- Backend selection is now strictly explicit per cell: `language` must be `\"py\"` or `\"js\"`. The previous `*** Cell` header parser, the `eval.lark` constrained grammar, and the sniffer-based fallback have all been removed.\n- `EvalTool.customFormat` no longer exists. Tool calls flow through the standard JSON schema; there is no Lark-constrained sampling path.\n- `tool.<name>()` exists only in JS. Python prelude helpers do not call back into the full tool registry.\n- JS helper paths reject protocol URIs (`://`) in `resolvePath()`; the JS prelude is filesystem-only unless the code calls `tool.read(...)` or another tool explicitly.\n- Python helper `output(...)` depends on `SKC_SESSION_FILE`; it fails outside a session-backed run.\n- `display()` can produce text and structured outputs from the same value; the renderer prefers markdown over `text/plain` when both exist.\n- JS static imports are rewritten only at top level. Nested imports stay invalid and surface normal JS syntax/runtime errors.\n- `EvalTool` is `concurrency = \"exclusive\"`, so eval calls do not overlap within a session.\n- The tool description shown to the model is templated by backend availability (`getEvalToolDescription()`); if Python is unavailable, the prompt omits Python-specific instructions.\n",
|
|
116
117
|
"tools/find.md": "# find\n\n> Find filesystem paths by glob; use `search` when you need content matches instead of path matches.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/find.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/find.md`\n- Key collaborators:\n - `packages/coding-agent/src/tools/path-utils.ts` — normalize inputs; split base path vs glob.\n - `packages/coding-agent/src/tools/list-limit.ts` — apply result-count caps.\n - `packages/coding-agent/src/session/streaming-output.ts` — truncate text output at byte cap.\n - `packages/coding-agent/src/tools/tool-result.ts` — build `content` and `details.meta`.\n - `packages/coding-agent/src/tools/output-meta.ts` — encode limit / truncation metadata.\n - `packages/coding-agent/src/tools/tool-errors.ts` — map user-facing tool errors.\n - `packages/coding-agent/src/tools/index.ts` — register the built-in local implementation.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | `string[]` | Yes | One or more globs, files, or directories. Empty strings are rejected. Multiple entries may be merged into one brace-union search when their base paths can be resolved together. |\n| `hidden` | `boolean` | No | Whether hidden files are included. Defaults to `true` (`hidden ?? true`). |\n| `limit` | `number` | No | Max returned paths. Defaults to `1000`. Must be a finite positive number; non-integers are floored. |\n\n## Outputs\nThe tool returns a single text block plus structured `details`.\n\n- Success text: newline-delimited paths, one per line, relative to the session cwd when possible; absolute when outside cwd. Exact file inputs return that file path as one line.\n- Empty result text: `No files found matching pattern`.\n- Multi-path partial miss: appends `Skipped missing paths: ...` after the result block, or after the empty-result line.\n- `details` may include:\n - `scopePath`: display form of the searched root or merged roots.\n - `fileCount`: number of paths returned after result limiting.\n - `files`: returned paths as an array.\n - `truncated`: whether result count or byte truncation occurred.\n - `resultLimitReached`: reached result limit.\n - `missingPaths`: skipped missing inputs in multi-path calls.\n - `truncation` / `meta.limits`: structured truncation and limit metadata for renderers.\n- Streaming: when the runtime supplies `onUpdate`, the local implementation emits incremental newline-delimited text snapshots during globbing, throttled to 200 ms.\n\n## Flow\n1. `FindTool.execute()` normalizes each `paths` entry with `normalizePathLikeInput()` and `/\\\\/g -> \"/\"` (`packages/coding-agent/src/tools/find.ts`). Empty normalized entries fail with `` `paths` must contain non-empty globs or paths ``.\n2. For multi-path local calls, `partitionExistingPaths(..., parseFindPattern)` (`packages/coding-agent/src/tools/path-utils.ts`) stats each base path. Missing entries are skipped; if all are missing, the tool throws `Path not found: ...`. Single missing paths still hard-fail.\n3. The tool tries `resolveExplicitFindPatterns()` to merge multiple inputs into one search rooted at a common base path. If that does not apply, it parses one input with `parseFindPattern()`.\n4. `parseFindPattern()` determines `(basePath, globPattern, hasGlob)`:\n - no glob chars (`*`, `?`, `[`, `{`) => search that path with implicit `**/*`.\n - glob in the first segment => search from `.` and, unless the pattern already starts with `**/`, prefix it with `**/`.\n - glob later in the path => split at the first glob-bearing segment.\n5. `resolveToCwd()` converts the base path to an absolute path under the session cwd. A resolved `/` is rejected with `Searching from root directory '/' is not allowed`.\n6. `limit` is defaulted to `DEFAULT_LIMIT` (`1000`) and validated as a positive finite integer. `hidden` defaults to `true`. The tool also creates a 5 s timeout via `AbortSignal.timeout(GLOB_TIMEOUT_MS)`.\n7. Execution then branches:\n - **Custom operations branch**: if `FindToolOptions.operations.glob` exists, the tool checks existence with `operations.exists()`, short-circuits exact-file inputs via `operations.stat()` when available, then calls `operations.glob(globPattern, searchPath, { ignore: [\"**/node_modules/**\", \"**/.git/**\"], limit })`.\n - **Built-in local branch**: the tool stats `searchPath`. Exact-file inputs return immediately. Directory inputs call `natives.glob()` with `fileType: File`, `hidden`, `maxResults: limit`, `sortByMtime: true`, `gitignore: true`, and the combined abort signal.\n8. In the local branch, optional `onMatch` callbacks convert each match to a cwd-relative display path and emit throttled progress updates.\n9. After native glob returns, JS sorts `result.matches` by `mtime` descending (`(b.mtime ?? 0) - (a.mtime ?? 0)`) before formatting paths.\n10. `buildResult()` applies `applyListLimit()` to cap the array again at `limit`, joins paths with `\\n`, then runs `truncateHead()` with `maxLines: Number.MAX_SAFE_INTEGER`. In practice this leaves the 50 KB byte cap in place while disabling the default 3000-line cap.\n11. `toolResult()` packages text plus `details`, and records result-limit / truncation metadata for renderers.\n\n## Modes / Variants\n- **Exact file path**: if the parsed input has no glob and the resolved path stats as a file, output is that one path.\n- **Directory path**: if the parsed input has no glob and stats as a directory, the tool searches it with implicit `**/*`.\n- **Single glob path**: one input parsed by `parseFindPattern()`.\n- **Merged multi-path search**: multiple inputs resolved by `resolveExplicitFindPatterns()` into one brace-union glob rooted at a common base path.\n- **Partial multi-path search with missing inputs**: local multi-path calls skip missing base paths and surface them as `missingPaths` / `Skipped missing paths: ...`.\n- **Custom delegated search**: uses injected `FindOperations` instead of local fs + native glob.\n\n## Side Effects\n- Filesystem\n - Stats the resolved base path, and in local multi-path mode stats every candidate base path up front.\n - Does not write files.\n- Subprocesses / native bindings\n - Built-in local mode calls the native `@sayknow-cli/natives` glob implementation.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n - Emits structured progress updates when `onUpdate` is provided.\n - Adds truncation / limit metadata to the tool result.\n- Background work / cancellation\n - Local globbing is cancellable through the caller abort signal plus an internal 5 s timeout.\n\n## Limits & Caps\n- Default result limit: `1000` (`DEFAULT_LIMIT` in `packages/coding-agent/src/tools/find.ts`).\n- Local glob timeout: `5000` ms (`GLOB_TIMEOUT_MS` in `packages/coding-agent/src/tools/find.ts`).\n- Output byte cap: `50 * 1024` bytes (`DEFAULT_MAX_BYTES` in `packages/coding-agent/src/session/streaming-output.ts`).\n- Default generic line cap in `truncateHead()` is `3000`, but `find` overrides `maxLines` to `Number.MAX_SAFE_INTEGER`, so byte size — not line count — is the practical output truncation cap.\n- Streaming update throttle: `200` ms between `onUpdate` emissions.\n- Sort order: most recent `mtime` first in the built-in local branch and promised in the prompt. The tool re-sorts in JS even though native glob receives `sortByMtime: true` so native code can still stop early at `maxResults`.\n\n## Errors\n- User-facing `ToolError`s from `FindTool.execute()` include:\n - `` `paths` must contain non-empty globs or paths ``\n - `Path not found: ...`\n - `Searching from root directory '/' is not allowed`\n - `Limit must be a positive number`\n - `Path is not a directory: ...`\n - `find timed out after 5s`\n- If the caller aborts, the local branch converts `AbortError` into `ToolAbortError`.\n- Non-`ENOENT` stat failures and other unexpected errors are rethrown.\n- Empty matches are not errors; they return the no-files text result.\n\n## Notes\n- Reach for `find` for filename / path discovery. Reach for `search` when the selection criterion is file contents or regex matches; `search` takes a `pattern` and returns anchored content matches, while `find` only returns matching paths (`packages/coding-agent/src/prompts/tools/find.md`, `packages/coding-agent/src/prompts/tools/search.md`).\n- Bare top-level globs are made recursive. `*.ts` is parsed as base `.` plus glob `**/*.ts`; `src/*.ts` stays rooted at `src` with a non-recursive `*.ts` segment; `src/**/*.ts` preserves explicit recursion.\n- `.gitignore` is always enabled in the built-in local branch (`gitignore: true`). There is no model-facing flag to disable it.\n- `hidden` defaults to `true`; hidden-file exclusion is opt-out, not opt-in.\n- Multi-path missing-input tolerance only applies in the built-in local branch. The custom-operations branch hard-fails the first missing `searchPath` it checks.\n- The custom `FindOperations.glob()` hook receives `ignore` and `limit`, but not the `hidden` flag or an explicit `.gitignore` toggle. A remote delegate must account for that itself if it wants parity with the local branch.\n- Built-in local globbing asks the native layer for `fileType: File`, so recursive directory searches yield files, not directories. Directory outputs are only possible through exact-path passthrough or custom delegates that return them.\n",
|
|
117
118
|
"tools/github.md": "# github\n\n> Dispatch GitHub CLI operations for repositories, issues, pull requests, search, and Actions run watching.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/gh.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/github.md`\n- Key collaborators:\n - `packages/coding-agent/src/tools/gh-format.ts` — shorten commit SHAs for summaries.\n - `packages/coding-agent/src/tools/gh-renderer.ts` — TUI rendering, especially `run_watch` live/result views.\n - `packages/coding-agent/src/utils/git.ts` — `gh`/`git` process wrappers, repo locking, branch config writes.\n - `packages/utils/src/dirs.ts` — base directory for dedicated PR worktrees.\n - `packages/coding-agent/src/sdk/session.ts` — session artifact allocation hook.\n - `packages/coding-agent/src/session/artifacts.ts` — artifact filename format `<id>.<toolType>.log`.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"repo_view\" \\| \"pr_create\" \\| \"pr_checkout\" \\| \"pr_push\" \\| \"search_issues\" \\| \"search_prs\" \\| \"search_code\" \\| \"search_commits\" \\| \"search_repos\" \\| \"run_watch\"` | Yes | Dispatch selector. `GithubTool.execute()` switches only on this field. |\n| `repo` | `string` | No | `owner/repo` override. Ignored when the identifier argument is already a full GitHub URL. For `search_issues`/`search_prs`/`search_code`/`search_commits`, defaults to the current checkout's `owner/repo` when omitted (skipped when the query already contains a `repo:`/`org:`/`user:`/`owner:` qualifier or when current-repo resolution fails). Required in practice when `gh` cannot infer repo context from the current checkout. |\n| `branch` | `string` | No | Used by `repo_view`, `pr_push`, and `run_watch`. `run_watch` falls back to current git branch when `run` is omitted; `pr_push` falls back to current branch. |\n| `pr` | `string \\| string[]` | No | Used by `pr_checkout`. Each item may be a PR number, branch name, or GitHub PR URL. Array form enables batching. Omitted means current branch PR. |\n| `force` | `boolean` | No | Used only by `pr_checkout`. Defaults to `false`; allows resetting an existing `pr-<number>` local branch to the PR head commit. |\n| `forceWithLease` | `boolean` | No | Used only by `pr_push`; passed through to git push. |\n| `title` | `string` | No | Used only by `pr_create`. Required unless `fill` is `true`. |\n| `body` | `string` | No | Used only by `pr_create`. Mutually exclusive with `fill`. Empty/omitted body becomes `--body \"\"` to suppress the interactive editor. Non-empty body is written to a temp file and passed as `--body-file`. |\n| `base` | `string` | No | Used only by `pr_create`; passed as `--base`. |\n| `head` | `string` | No | Used only by `pr_create`; passed as `--head`. |\n| `draft` | `boolean` | No | Used only by `pr_create`. Defaults to `false`. |\n| `fill` | `boolean` | No | Used only by `pr_create`. Defaults to `false`. Mutually exclusive with `title` and `body`. |\n| `reviewer` | `string[]` | No | Used only by `pr_create`; each entry becomes `--reviewer`. |\n| `assignee` | `string[]` | No | Used only by `pr_create`; each entry becomes `--assignee`. |\n| `label` | `string[]` | No | Used only by `pr_create`; each entry becomes `--label`. |\n| `query` | `string` | No | Used by all `search_*` ops. Required there. |\n| `limit` | `number` | No | Used by all `search_*` ops. Defaults to `10`, floored, clamped to `50`, and must be `> 0`. |\n| `run` | `string` | No | Used only by `run_watch`. Must be a numeric run ID or full GitHub Actions run URL. |\n| `tail` | `number` | No | Used only by `run_watch`. Defaults to `15`, floored, clamped to `200`, and must be `> 0`. |\n\n## Outputs\nThe tool returns a single text result built by `buildTextResult()` in `packages/coding-agent/src/tools/gh.ts`.\n\n- `content`: one text block. Multi-item ops join sections with blank lines and `---` separators.\n- `sourceUrl`: set for single repo/PR/run results when a canonical URL is known.\n- `details`: optional structured metadata used by the TUI renderer.\n - Common fields: `artifactId`, `repo`, `branch`, `worktreePath`, `remote`, `remoteBranch`, `headSha`, `runId`, `runIds`, `status`, `conclusion`, `failedJobs`.\n - `pr_checkout` adds `checkouts: GhPrCheckoutSummary[]`.\n - `run_watch` adds `watch: GhRunWatchViewDetails`, which drives the custom live/result renderer in `packages/coding-agent/src/tools/gh-renderer.ts`.\n- Artifact trailer: when `artifactId` is present, the text body gets an appended line like `Full failed-job logs: artifact://<id>`.\n - `run_watch` allocates artifacts with `session.allocateOutputArtifact(\"github\")`; persistent sessions therefore save failed-log bodies as `<artifact-dir>/<id>.github.log`.\n\n`run_watch` is the only streaming op. It emits `onUpdate` snapshots while polling, then returns one final text result.\n\n## Flow\n1. `GithubTool.createIf()` exposes the tool only when `git.github.available()` finds `gh` on `PATH`.\n2. `GithubTool.execute()` wraps dispatch in `untilAborted()` and switches on `params.op`.\n3. Each op normalizes optional strings, arrays, booleans, and numeric caps locally in `packages/coding-agent/src/tools/gh.ts`.\n4. CLI execution goes through `git.github.run/json/text()` in `packages/coding-agent/src/utils/git.ts`:\n - spawns `gh ...` with `Bun.spawn()`;\n - trims stdout/stderr unless `trimOutput: false`;\n - maps common auth/repo-context failures into tool-facing `ToolError` messages;\n - `json()` rejects empty or invalid JSON.\n5. Read-style ops (`repo_view`, `search_*`) fetch JSON and format Markdown-like text summaries. Single-issue and single-PR views were moved out of the tool and now resolve through the `issue://` / `pr://` internal URL schemes, which share the same SQLite cache.\n7. PR diffs moved out of the tool. `pr://<N>/diff` lists changed files, `pr://<N>/diff/<i>` slices a single file, and `pr://<N>/diff/all` returns the full unified diff — see `docs/tools/read.md`. All three variants share one `gh pr diff` invocation through the `pr-diff` cache row.\n8. `pr_checkout` resolves PR metadata first, then enters `git.withRepoLock()` before any git mutation so parallel checkout calls for the same primary repo do not race on shared `.git` state.\n9. `pr_push` reads PR head metadata back from git branch config, derives a refspec, then pushes with `git.push()`.\n10. `pr_create` shells out once, then best-effort re-reads the created PR for a richer summary.\n11. `run_watch` chooses either run mode (`run` supplied) or commit mode (`run` omitted), polls GitHub Actions APIs every 3 seconds, emits streaming updates, and may save a full failed-log artifact before returning.\n12. Final text goes through `toolResult().text(...)`; if `session.allocateOutputArtifact()` returns a slot, failed-log text is persisted with `Bun.write()`.\n\n## Modes / Variants\n\n### `repo_view`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `branch` |\n| `gh` command | `gh repo view [<repo>] [--branch <branch>] --json <GH_REPO_FIELDS>` |\n| Batching | None |\n| Output | `# <owner/repo>` header, description, URL, default branch, requested branch, visibility, permission, primary language, stars, forks, archive/fork flags, updated timestamp, homepage, topics. `sourceUrl = data.url`. |\n\nIf `repo` is omitted, `gh` repository resolution is used.\n\nSingle-issue and single-PR reads live in the `issue://<N>` / `pr://<N>` URL schemes (see `docs/tools/read.md`). They share `~/.skc/cache/github-cache.db` (override via `SKC_GITHUB_CACHE_DB`) and the `github.cache.softTtlSec` / `github.cache.hardTtlSec` / `github.cache.enabled` settings. The cache retains rendered Markdown plus the raw JSON payload returned by `gh`, including private bodies, comments, reviews, and review comments when comments are enabled; rows are scoped by the local GitHub credential fingerprint. Root and repo-scoped reads (`issue://`, `pr://owner/repo`) issue a live `gh issue list` / `gh pr list` for browsing; query params `state`, `limit`, `author`, `label` pass through to `gh` (`issue://` accepts `state=open|closed|all`; `pr://` also accepts `merged`). PR diffs ride the same cache under `pr://<N>/diff[/…]`: the listing, full diff, and per-file slices all share one `pr-diff` row keyed by repo and PR number.\n\n### `pr_create`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` plus either `fill=true` or `title` |\n| Optional fields | `repo`, `title`, `body`, `base`, `head`, `draft`, `fill`, `reviewer[]`, `assignee[]`, `label[]` |\n| `gh` command | `gh pr create ...` with flags assembled from provided fields |\n| Batching | None |\n| Output | `# Created Pull Request ...` summary with URL, state, draft flag, base/head, author, created time, labels, optional body. `sourceUrl` is the created PR URL. |\n\nBranches:\n- `fill && (title || body !== undefined)` throws.\n- Non-empty `body` is written under a temp dir `gh-pr-body-*` in `os.tmpdir()`, passed as `--body-file`, then removed in `finally`.\n- After creation, the tool parses the returned URL and best-effort runs `gh pr view <number> --repo <repo> --json <GH_PR_FIELDS_NO_COMMENTS>`; failures there are swallowed.\n\n### `pr_checkout`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `pr`, `force` |\n| `gh` command | For each requested PR: `gh pr view [<pr>] [--repo <repo>] --json <GH_PR_CHECKOUT_FIELDS>`; cross-repo PRs may also call `gh repo view <headRepository> --json <GH_REPO_CLONE_FIELDS>`. |\n| Batching | Yes. `pr` may be `string[]`; each PR is resolved in parallel, but git mutations are serialized per primary repo by `git.withRepoLock()`. |\n| Output | Single PR: checkout/worktree summary plus `details.repo`, `details.branch`, `details.worktreePath`, `details.remote`, `details.remoteBranch`, `details.checkouts`. Batched: `# <n> Pull Request Worktrees (...)` plus one section per PR and aggregated `details.checkouts`. |\n\nWorktree and metadata behavior:\n- Local branch name is always `pr-<number>`.\n- Worktree path is `path.join(getWorktreesDir(), encodeRepoPathForFilesystem(primaryRepoRoot), localBranch)`, where `getWorktreesDir()` is `~/.skc/wt`; effective path is `~/.skc/wt/<encoded-primary-repo-root>/pr-<number>`.\n- Existing worktree detection is by branch ref `refs/heads/pr-<number>` from `git.worktree.list()`.\n- New worktree creation calls `git.worktree.add(repoRoot, finalWorktreePath, localBranch, { signal })` after verifying the path is neither already registered nor already present on disk.\n- For same-repo PRs, remote is `origin`. For cross-repo PRs, the tool resolves a clone URL for the head repo, reuses an existing remote with the same URL when possible, or creates `fork-<owner>` / `fork-<owner>-<n>`.\n- The branch push metadata is persisted with `git config` under the repository's shared `.git/config` as:\n - `branch.pr-<number>.remote`\n - `branch.pr-<number>.merge`\n - `branch.pr-<number>.pushRemote`\n - `branch.pr-<number>.skcPrHeadRef`\n - `branch.pr-<number>.skcPrUrl`\n - `branch.pr-<number>.skcPrIsCrossRepository`\n - `branch.pr-<number>.skcPrMaintainerCanModify`\n- If `refs/heads/pr-<number>` already exists at a different commit, checkout fails unless `force=true`, in which case `git branch --force` resets it to the fetched PR head.\n- If a matching worktree already exists, the tool reuses it and reports `reused: true`.\n\n### `pr_push`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `branch`, `forceWithLease` |\n| `gh` command | None. This path uses git, not `gh`. |\n| Batching | None |\n| Output | `# Pushed Pull Request Branch` summary with local branch, remote, remote branch, remote URL, PR URL, and force-with-lease flag. `sourceUrl = prUrl` when known. |\n\nPush target resolution reads the `branch.<name>.skcPrHeadRef`, `pushRemote`/`remote`, `skcPrUrl`, `skcPrMaintainerCanModify`, and `skcPrIsCrossRepository` git-config keys written by `pr_checkout`. If the current checked-out branch matches the target branch, the source ref is `HEAD`; otherwise it pushes `refs/heads/<branch>`. The refspec is `HEAD:refs/heads/<headRef>` or `refs/heads/<branch>:refs/heads/<headRef>`.\n\n### `search_issues`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/issues -f q=\"<query> [repo:<repo>] is:issue\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub issues search`, echoed query, optional repo, result count, then one bullet per issue with repo/state/author/labels/timestamps/URL. |\n\n`repo` defaults to the current checkout's `owner/repo` via `resolveSearchRepoScope()` when omitted. The default is suppressed when the query already contains a leading `repo:`/`org:`/`user:`/`owner:` qualifier or when `gh repo view` fails to resolve the current checkout (e.g. outside a github remote).\n\n### `search_prs`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/issues -f q=\"<query> [repo:<repo>] is:pr\" -F per_page=<limit>` |\n| Batching | None |\n| Output | Same shape as `search_issues`, labeled as pull requests. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_code`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/code -f q=\"<query> [repo:<repo>]\" -F per_page=<limit> -H \"Accept: application/vnd.github.text-match+json\"` |\n| Batching | None |\n| Output | `# GitHub code search`, result count, then one bullet per match with path, repo, short commit SHA, URL, and first normalized text-match fragment line when present. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_commits`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `repo`, `limit` |\n| `gh` command | `gh api -X GET /search/commits -f q=\"<query> [repo:<repo>]\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub commits search`, result count, then one bullet per commit: short SHA + first commit-message line, repo, author, date, URL. |\n\n`repo` defaults to the current checkout's `owner/repo` as in `search_issues`.\n\n### `search_repos`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op`, `query` |\n| Optional fields | `limit` |\n| `gh` command | `gh api -X GET /search/repositories -f q=\"<query>\" -F per_page=<limit>` |\n| Batching | None |\n| Output | `# GitHub repositories search`, result count, then one bullet per repo with first description line, language, stars, forks, open issues, visibility, archive/fork flags, updated time, URL. |\n\n`repo` is intentionally not used for this op.\n\n### `run_watch`\n\n| Aspect | Value |\n| --- | --- |\n| Required fields | `op` |\n| Optional fields | `repo`, `branch`, `run`, `tail` |\n| `gh` command | Repo resolution: `gh repo view --json nameWithOwner -q .nameWithOwner` when `repo` and run URL repo are both absent. Single-run mode uses `gh api --method GET /repos/<repo>/actions/runs/<runId>` and `gh api --method GET /repos/<repo>/actions/runs/<runId>/jobs`. Commit mode uses `gh api --method GET /repos/<repo>/branches/<branch>`, `gh api --method GET /repos/<repo>/actions/runs`, `gh api --method GET /repos/<repo>/actions/runs/<runId>/jobs`, and `gh api /repos/<repo>/actions/jobs/<jobId>/logs` for failed jobs. |\n| Batching | Implicit batching only in commit mode: all workflow runs for one commit are tracked together. |\n| Output | Streaming watch snapshots via `onUpdate`, then a final text report. On failure, appends `Full failed-job logs: artifact://<id>` and sets `details.artifactId`. |\n\nWatch flow:\n- `run` parsing accepts either a decimal run ID or a full run URL. URL repo must match explicit `repo` when both are given.\n- Poll interval is fixed at 3 seconds (`RUN_WATCH_INTERVAL_DEFAULT`).\n- Failure grace period is fixed at 5 seconds (`RUN_WATCH_GRACE_DEFAULT`). When any failed job appears before completion, the tool emits a note, waits once, re-fetches state, then collects logs so concurrent failures are included.\n- Failed-job logs are fetched with `gh api /repos/<repo>/actions/jobs/<jobId>/logs` via `git.github.run()`, not `json()`. Non-zero exit leaves `available: false` instead of failing the whole watch.\n- Inline result includes only the last `tail` lines per failed job. The saved artifact contains full logs (`mode: \"full\"`).\n- In commit mode, success is intentionally double-checked: once all known runs are successful, the tool waits one more poll interval and succeeds only if the set of run IDs is unchanged. This avoids returning before late workflow runs appear for the same commit.\n- `details.watch` drives a specialized renderer in `packages/coding-agent/src/tools/gh-renderer.ts`; non-watch results fall back to generic text rendering.\n\n## Side Effects\n- Filesystem\n - `pr_create` may create a temp dir under `os.tmpdir()` named `gh-pr-body-*`, write `body.md`, then remove the dir in `finally`.\n - `pr_checkout` may create directories under `~/.skc/wt/<encoded-primary-repo-root>/` and add git worktrees there.\n - `run_watch` may write a session artifact with full failed-job logs.\n- Network\n - Every op shells out to `gh`, which then talks to GitHub APIs except `pr_push`.\n - `pr_push` uses git network transport to the configured remote.\n- Subprocesses / native bindings\n - All `gh` calls use `Bun.spawn([\"gh\", ...args])`.\n - `pr_checkout` and `pr_push` also invoke git helpers from `packages/coding-agent/src/utils/git.ts`.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n - `run_watch` consumes `session.allocateOutputArtifact()` when failed-job logs are persisted.\n - Returned `details` objects carry run/checkouts metadata for the renderer/UI.\n- User-visible prompts / interactive UI\n - `gh` interactive editor fallback is suppressed for `pr_create` by forcing either `--body-file` or `--body \"\"`.\n - `gh-renderer` provides compact headers for all ops and a custom live watch view for `run_watch`.\n- Background work / cancellation\n - `run_watch` loops until success/failure and uses `scheduler.wait()` between polls.\n - `GithubTool.execute()` is wrapped in `untilAborted()`; `git.github.run()` forwards the abort signal into `Bun.spawn()`.\n\n## Limits & Caps\n- Search result default: `10` (`SEARCH_LIMIT_DEFAULT` in `packages/coding-agent/src/tools/gh.ts`).\n- Search result max: `50` (`SEARCH_LIMIT_MAX`).\n- PR file preview inside the `pr://` view: first `50` files only (`FILE_PREVIEW_LIMIT` in `gh.ts`).\n- Run-watch poll interval: `3s` (`RUN_WATCH_INTERVAL_DEFAULT`).\n- Run-watch failure grace period: `5s` (`RUN_WATCH_GRACE_DEFAULT`).\n- Run-watch failed-log tail default: `15` lines (`RUN_WATCH_TAIL_DEFAULT`).\n- Run-watch failed-log tail max: `200` lines (`RUN_WATCH_TAIL_MAX`).\n- PR review comments page size: `100` (`REVIEW_COMMENTS_PAGE_SIZE`).\n- Actions jobs page size: `100` (`RUN_JOBS_PAGE_SIZE`).\n- Search and tail numeric inputs are floored with `Math.floor()`, clamped to the max, and rejected when non-finite or `<= 0`.\n- `pr_checkout` batch fan-out is unbounded in tool code; all requested PRs are launched with `Promise.all()`.\n\n## Errors\n- Tool creation is skipped entirely when `gh` is not installed.\n- `git.github.run()` throws `ToolError(\"GitHub CLI (gh) is not installed...\")` if `gh` is missing at execution time.\n- `git.github.text/json()` map common failures to model-facing messages:\n - not authenticated → `GitHub CLI is not authenticated. Run \\`gh auth login\\`.`\n - missing repo context without explicit `repo` → `GitHub repository context is unavailable. Pass \\`repo\\` explicitly or run the tool inside a GitHub checkout.`\n - otherwise stderr/stdout text, or fallback `GitHub CLI command failed: gh ...`\n- `json()` also throws on empty stdout or invalid JSON.\n- Local validation errors throw `ToolError`, including:\n - missing required per-op fields (`query`, `title unless fill=true`)\n - invalid numeric `limit` / `tail`\n - invalid `run` format\n - `fill` combined with `title` or `body`\n - missing git repo / branch / HEAD context for checkout, push, or watch\n - `pr_push` on a branch without `skcPrHeadRef` metadata\n - conflicting existing worktree path or branch without `force`\n- `run_watch` treats failed-job log fetches specially: missing log content does not fail the watch; it marks that log `available: false` and prints `Log tail unavailable.` / `Full log unavailable.`.\n- `pr_create` swallows only the post-create best-effort `gh pr view` refresh; the create step itself still fails normally.\n\n## Notes\n- `appendRepoFlag()` intentionally skips `--repo` when the identifier argument is already a full GitHub URL; that lets `gh` derive repo/number from the URL.\n- `normalizePrIdentifierList()` accepts `reviewer`, `assignee`, and `label` arrays too; the helper name is broader than its callers.\n- `pr_push` depends on `pr_checkout` having run first for that local branch; there is no alternate metadata source.\n- `pr_checkout` stores push metadata in branch config, not in the worktree directory. Reusing the same `pr-<number>` branch reuses those config keys.\n- Worktree write serialization is keyed by the primary repo root, not the current worktree path, because git worktrees share `.git/config`, `packed-refs`, commit-graph, and worktree metadata files.\n- `search_repos` is the only search op that never forwards `repo`; repository scoping must be expressed in the query itself.\n- `run_watch` success on commit mode means “all observed runs succeeded and no additional runs appeared one poll later”, not merely “latest poll looked green”.\n- The TUI renderer collapses failed log previews unless the result view is expanded; the underlying text result still contains the same tailed lines plus any artifact reference.\n",
|
|
119
|
+
"tools/gitlab.md": "# gitlab\n\n> Create and inspect GitLab merge requests and pipelines through the GitLab CLI (`glab`).\n\n## Source\n- Entry: `packages/coding-agent/src/tools/gitlab.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/gitlab.md`\n- Key collaborators:\n - `packages/coding-agent/src/utils/git.ts` — `gitlab` namespace: non-interactive `glab` spawn, JSON parsing, error cleanup.\n\n## Availability\n- Registered only when `glab` is on `PATH` (`GitlabTool.createIf`).\n- Callable only when the `gitlab.enabled` setting is `true` (default `false`). The tool is `discoverable`.\n- Works with gitlab.com and any self-hosted instance that `glab auth login` has a token for. The host comes from the checkout's git remote or from `repo`.\n\n## Inputs\n\n| Field | Type | Used by | Description |\n| --- | --- | --- | --- |\n| `op` | `\"mr_create\" \\| \"mr_view\" \\| \"mr_list\" \\| \"ci_status\"` | all | Dispatch selector. |\n| `repo` | `string` | all | `OWNER/REPO`, `GROUP/NAMESPACE/REPO`, or project URL; passed as `--repo`. Defaults to the current checkout. |\n| `mr` | `string` | `mr_view`, `ci_status` | `mr_view`: iid, URL, or source branch (default: the current branch's MR). `ci_status`: merge request iid (digits only). |\n| `title` | `string` | `mr_create` | Required unless `fill` is `true`. |\n| `description` | `string` | `mr_create` | Markdown. Omitted means `--description \"\"` so glab never prompts. |\n| `source` | `string` | `mr_create`, `mr_list` | Source branch. `mr_create` defaults to the current branch and fails on a detached HEAD. |\n| `target` | `string` | `mr_create`, `mr_list` | Target branch. `mr_create` omits it so glab uses the project default. |\n| `draft` | `boolean` | `mr_create` | `--draft`. |\n| `fill` | `boolean` | `mr_create` | `--fill`; mutually exclusive with `title`/`description`. glab also pushes the branch. |\n| `push` | `boolean` | `mr_create` | `--push` (ignored with `fill`, which already pushes). |\n| `reviewer`, `assignee`, `label` | `string[]` | `mr_create` (`label` also `mr_list`) | Repeated flags; blank entries are dropped. |\n| `removeSourceBranch`, `squash` | `boolean` | `mr_create` | `--remove-source-branch=<bool>`, `--squash-before-merge=<bool>`. |\n| `state` | `\"opened\" \\| \"merged\" \\| \"closed\" \\| \"all\"` | `mr_list` | Default `opened`. |\n| `branch` | `string` | `ci_status` | Pipeline branch (default: current branch). |\n| `limit` | `number` | `mr_list` | Default 10, clamped to 1..50. |\n\n## Behaviour\n- `mr_create` first runs `glab mr list --source-branch <source> [--target-branch <target>] --output json`. If an `opened` MR exists, it is returned with `created: false` and nothing is created. Otherwise it runs `glab mr create --yes ...`, takes the `/-/merge_requests/<iid>` URL from the output (error if none), and fetches `glab mr view <iid> --output json` for the summary (best effort).\n- `mr_view` renders state, draft flag, branches, author, reviewers, labels, `detailed_merge_status`, conflicts, head pipeline, and the description (truncated at 4000 chars).\n- `ci_status` runs `glab ci get --output json [--branch|--merge-request]` and lists jobs as `[status] stage/name (failure_reason)`. \"No pipeline found\" is a normal `# No pipeline` result, not an error.\n- Every `glab` call runs with `stdin` closed and `NO_COLOR=1`, `GLAB_NO_PROMPT=1`, `GLAB_CHECK_UPDATE=false`, `GLAB_SEND_TELEMETRY=false`. JSON parsing skips notices glab prints on stdout before the payload. Error banners are reduced to one line; authentication failures point to `glab auth login`.\n\n## Outputs\nOne text block; `details` carries `{ op, url?, iid?, created? }` and the result `sourceUrl` is the MR or pipeline URL when known.\n\n## Not supported\n- MR checkout, merge, approve, and comments. Use `bash` with `glab` for those.\n- Live pipeline watching (`ci_status` is a single snapshot).\n",
|
|
118
120
|
"tools/irc.md": "# irc\n\n> Send short prose messages to other live agents in the current process.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/irc.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/irc.md`\n- Key collaborators:\n - `packages/coding-agent/src/registry/agent-registry.ts` — process-global live agent directory.\n - `packages/coding-agent/src/session/agent-session.ts` — side-channel reply generation and history injection.\n - `packages/coding-agent/src/prompts/system/irc-incoming.md` — no-tools auto-reply prompt.\n - `packages/coding-agent/src/tools/index.ts` — tool availability gating.\n - `packages/coding-agent/src/config/settings-schema.ts` — `irc.enabled` default.\n - `packages/coding-agent/src/modes/controllers/event-controller.ts` — renders IRC events into chat UI.\n - `packages/coding-agent/src/modes/utils/ui-helpers.ts` — formats `[IRC]` transcript lines.\n - `packages/coding-agent/src/task/executor.ts` — carries `irc.enabled` into subagents.\n\n## Inputs\n\n### `op: \"list\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"list\"` | Yes | Lists peers visible to the caller. |\n\n### `op: \"send\"`\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `op` | `\"send\"` | Yes | Sends one message to one peer or to `\"all\"`. |\n| `to` | `string` | Yes | Peer id such as `0-Main`, or `\"all\"` for broadcast. Whitespace is trimmed. |\n| `message` | `string` | Yes | Message body. Whitespace is trimmed; empty-after-trim is rejected. |\n| `awaitReply` | `boolean` | No | Wait for prose replies. Defaults to `true` for direct messages and `false` for `to: \"all\"`. |\n\n## Outputs\n- Single-shot `AgentToolResult`; no streaming updates.\n- `content` is one text block.\n - `list` returns either `No other live agents.` or a bullet list headed by `<n> peer(s):`.\n - `send` returns delivery summary text, then optional `## Replies`, `## Failed`, and `Unknown / unavailable peers:` sections.\n- `details` is structured metadata:\n - `list`: `{ op, from, peers, channels }`\n - `send`: `{ op, from, to, delivered, replies?, failed?, notFound? }`\n- The tool does not return raw IRC frames, message ids, or a transcript object.\n\n## Flow\n1. `IrcTool.createIf` only constructs the tool when `irc.enabled` is on and the session has both an `AgentRegistry` and `getAgentId` (`packages/coding-agent/src/tools/irc.ts`).\n2. Tool discovery adds another gate in `packages/coding-agent/src/tools/index.ts`: if the caller is `0-Main` and `async.enabled` is off, `irc` is hidden because the main agent cannot talk to concurrent peers in sync mode.\n3. `execute` resolves the process-global registry and sender id. Missing either returns a text error result instead of throwing.\n4. `op: \"list\"` calls `registry.listVisibleTo(senderId)`, which exposes every other agent in flat namespace whose status is `running` or `idle` (`packages/coding-agent/src/registry/agent-registry.ts`).\n5. `list` formats human-readable lines and returns `channels` as `['all', ...peerIds]`. These are logical targets only; there is no channel join state.\n6. `op: \"send\"` trims `to` and `message`; missing values produce text errors.\n7. `send` resolves targets:\n - `to === \"all\"`: all visible peers.\n - otherwise: one exact registry id, excluding self and excluding peers not in `running`/`idle`.\n8. `send` chooses `awaitReply = params.awaitReply ?? !isBroadcast`.\n9. Each target is dispatched in parallel via `target.session.respondAsBackground(...)`. One slow or failing peer does not block dispatch to the others.\n10. `respondAsBackground` accepts each delivery into the recipient's volatile current-session exchange queue before observing it in the recipient or main UI, and before reporting sender delivery success:\n - `awaitReply === false`: accepts/queues the incoming message, then emits its `irc_message` event and forwards the display-only relay to the main session UI.\n - `awaitReply === true`: renders `packages/coding-agent/src/prompts/system/irc-incoming.md` and runs `runEphemeralTurn` with `toolChoice: \"none\"`. After a reply succeeds, it constructs and accepts/queues the ordered incoming + auto-reply pair, commits its IRC roster claim, then emits both `irc_message` events and forwards both display-only relays. A failed or aborted reply turn accepts and surfaces nothing.\n11. Deferred injection waits until the recipient is no longer streaming; `#flushPendingBackgroundExchanges` appends accepted custom messages through normal `message_start`/`message_end` external events so persistence and listeners see them.\n12. `send` aggregates `delivered`, `replies`, `failed`, and `notFound`, then returns one text summary plus matching `details`.\n\n## Modes / Variants\n- `list`: enumerate visible peers and logical channels.\n- `send` direct message: one exact peer id, default synchronous auto-reply.\n- `send` broadcast: `to: \"all\"`, default fire-and-forget (`awaitReply: false`) to every visible peer.\n- `send` with `awaitReply: false`: recipient records the incoming message but does not generate a reply.\n- `send` with `awaitReply: true`: recipient performs a no-tools ephemeral LLM turn and returns prose.\n\n## Side Effects\n- Session state\n - Reads from the process-global `AgentRegistry`.\n - Accepts each IRC delivery into a process-local, volatile recipient exchange queue before recipient/main observations and sender success. This acceptance is not durable delivery.\n - Emits `irc_message` session events on recipient sessions after acceptance.\n - Flushes accepted IRC custom messages into recipient history after the current stream finishes.\n - For non-main recipients, forwards display-only relay observations into the main session UI after acceptance; these relays are not persisted to the main agent history. Observer failures are isolated from accepted delivery.\n - Subagents inherit `irc.enabled` from task executor settings.\n- User-visible prompts / interactive UI\n - IRC events render as `[IRC]` transcript lines in the TUI.\n - Auto-replies are generated from `packages/coding-agent/src/prompts/system/irc-incoming.md` and explicitly forbid tool use.\n- Background work / cancellation\n - `send` starts one background `respondAsBackground` call per target.\n - The caller's `AbortSignal` is forwarded into each background reply turn.\n- Network\n - No IRC server connection.\n - When `awaitReply: true`, the recipient may make model-provider API calls through `runEphemeralTurn`.\n- Filesystem\n - No direct filesystem writes in the tool itself.\n\n## Limits & Caps\n- Availability gates:\n - `irc.enabled` defaults to `true` in `packages/coding-agent/src/config/settings-schema.ts`.\n - Main agent tool discovery suppresses `irc` when `async.enabled` is off (`packages/coding-agent/src/tools/index.ts`).\n- Visibility scope: only peers in status `running` or `idle` are addressable via `listVisibleTo`.\n- Reply execution:\n - No tools are available in auto-reply turns (`toolChoice: \"none\"` in `runEphemeralTurn`).\n - No internal timeout, retry, backoff, rate limit, or reply length cap is defined in `irc.ts`; behavior relies on the underlying model stream and any upstream API limits.\n- Flush scheduling: deferred history injection polls every `50` ms while the recipient is still streaming (`#scheduleBackgroundExchangeFlush` in `packages/coding-agent/src/session/agent-session.ts`).\n\n## Errors\n- The tool returns text errors, not thrown exceptions, for:\n - missing registry: `IRC is unavailable in this session.`\n - missing sender id: `IRC is unavailable: caller has no agent id.`\n - missing `to`: `` `to` is required for op=\"send\". ``\n - missing `message`: `` `message` is required for op=\"send\". ``\n - unknown op: `Unknown irc op.`\n- Unknown, self-addressed, non-running, and non-idle direct targets are reported under `details.notFound` and in the text footer `Unknown / unavailable peers:`.\n- If a target has no attached session, it is treated as not found.\n- Exceptions from reply generation before awaited-exchange acceptance are caught per-target and surfaced under `details.failed` as `{ id, error }`; other recipients still complete. A provider failure or sender abort therefore emits no `irc_message` observations and accepts no recipient exchange. Recipient/main observer failures after acceptance are isolated and do not turn a delivered exchange into a sender failure.\n- If no target succeeds, `send` still returns normally with `No recipients received the message.` and optional `failed`/`notFound` metadata.\n\n## Notes\n- This is IRC-like naming only. There are no servers, sockets, nick registration, auth handshakes, channels beyond `all`, or commands such as join/part/topic.\n- Addressing is by exact agent id from the registry; there is no fuzzy lookup or aliasing.\n- `channels` in `list` is synthetic output: `all` plus visible peer ids. Nothing is persisted across calls as channel membership.\n- Recipient history, not sender history, receives accepted IRC custom messages when the recipient flushes its current-session queue. Acceptance is process-local and volatile: it does not promise durable storage, fsync, recovery, deduplication, or replay across process loss.\n- The main UI may show IRC relays for conversations it was not part of, but those relay records are explicitly display-only.\n- Because reply generation snapshots in-flight assistant text, a recipient can answer based on partially streamed context.\n- Direct self-messaging is rejected by resolving the target as unavailable.\n\n## Sidebar\n\n- `irc.sidebar.enabled` defaults to `true`: the read-only sidebar is available when `irc.enabled` is also enabled, but starts closed. `app.irc.sidebar.toggle` (default `Alt+I`, remappable) opens or hides it.\n- The sidebar retains the active runtime UI session's IRC observations only. It is not written to disk or restored into another session. Each arrival decides its inline lifetime once: arrivals while the panel is visible expire 10 seconds after observation; arrivals while it is closed persist inline. Later toggles do not change that decision.\n- An eligible first live inline arrival while the sidebar is closed shows a one-time hint using the resolved toggle key (for example, `Alt+I opens sidebar`). Rebuilds do not show or consume this hint.\n- When open, the transcript/sidebar split targets 70:30. The sidebar keeps a 30-column minimum only while the transcript can retain at least half the usable width; below that boundary the sidebar yields completely and the transcript renders full width. Retained sidebar messages are Discord-style blocks: `sender → recipient · HH:mm`, followed by the retained body with a two-column indent and one blank row between messages. Sender and recipient display fields are normalized and bounded to 256 UTF-8 bytes at complete grapheme boundaries.\n- The sidebar retains at most 10,000 observations and 16 MiB of UTF-8 message payload per runtime UI session, evicting the oldest observations first. An individual observation larger than the 16 MiB budget is omitted rather than truncated or admitted by evicting the rest of the backlog. Replay suppression tracks at most 100,000 unique observation identities and then fails closed for unseen arrivals until the runtime UI instance ends, preventing forgotten identities from resurrecting across eviction or fork cleanup while keeping memory bounded. Both inline transcript and sidebar body rendering independently materialize at most 2,048 rows from a bounded 64 KiB UTF-8 source projection, preferring recent retained content and showing explicit message/backlog elision markers when necessary. The bounded, runtime-only, read-only backlog does not affect welcome-screen row reservation, which counts transcript rows only.\n- While the sidebar is visible, Kitty terminals keep rendering real images in the transcript (Kitty placements are cursor-neutral and compose safely with the split). Cursor-advancing protocols — iTerm2 inline images and raw SIXEL sequences — are represented by compact text placeholders so they cannot corrupt the split. Hiding the sidebar restores normal rendering for every protocol.\n- A successful `/fork` starts a new logical UI session: it clears the sidebar ledger, hides the panel, and resets roster-delivery state. Failed or cancelled forks preserve the current runtime sidebar state.\n\n## Hidden peer roster reminders\n\nWhen the live peer roster changes, an eligible model turn receives one hidden single-line reminder listing stable agent ids and roster labels. The initial empty roster produces no reminder; a later transition to empty does. Running/idle status changes alone do not count as a roster change.\n\nNormal turns commit an atomic roster claim on successful completion. Awaited IRC auto-replies defer that commit until their incoming + auto-reply exchange is accepted; failed or aborted reply turns release the claim for a later retry. Isolated `/btw` turns do not acquire or commit roster claims. These reminders are context-only and never appear in the transcript or persisted history.",
|
|
119
121
|
"tools/job.md": "# job\n\n> Wait for or cancel background jobs managed by the session async runtime.\n\n## Source\n- Entry: `packages/coding-agent/src/tools/job.ts`\n- Model-facing prompt: `packages/coding-agent/src/prompts/tools/job.md`\n- Key collaborators:\n - `packages/coding-agent/src/async/job-manager.ts` — job registry, cancellation, delivery suppression.\n - `packages/coding-agent/src/async/support.ts` — feature gating for background jobs.\n - `packages/coding-agent/src/tools/bash.ts` — explicit async bash and auto-backgrounded bash jobs.\n - `packages/coding-agent/src/task/index.ts` — async task-job scheduling.\n - `packages/coding-agent/src/sdk/session.ts` — automatic follow-up delivery for unsuppressed completions.\n - `packages/coding-agent/src/config/settings-schema.ts` — `async.pollWaitDuration` options.\n\n## Inputs\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `poll` | `string[]` | No | Job ids to watch. Cannot be combined with `list`. If omitted (and `cancel` is also omitted), the tool watches all running jobs. If provided, missing ids are silently filtered out before waiting. |\n| `cancel` | `string[]` | No | Job ids to cancel before any polling. Missing ids are reported as `not_found`; non-running ids as `already_completed`. |\n| `list` | `boolean` | No | Return an immediate snapshot of every job spawned by the calling agent (running + completed within retention) without waiting. Read-only — cannot be combined with `poll` or `cancel`. |\n\n## Outputs\nThe tool returns one text block plus `details`.\n\n- `content[0].text`: markdown-like plain text sections assembled by `#buildResult(...)`:\n - `## Cancelled (N)` for cancel outcomes.\n - `## Completed (N)` for non-running jobs, including stored `resultText` and `errorText`.\n - `## Still Running (N)` for jobs still in `running`.\n- `details.jobs`: array of snapshots:\n - `id: string`\n - `type: \"bash\" | \"task\"`\n - `status: \"running\" | \"completed\" | \"failed\" | \"cancelled\"`\n - `label: string`\n - `durationMs: number`\n - optional `resultText`, `errorText`\n- `details.cancelled` appears only when `cancel` was passed; each item is `{ id, status }` where status is `\"cancelled\" | \"not_found\" | \"already_completed\"`.\n\nStreaming behavior:\n- During a polling wait, `execute(...)` emits `onUpdate(...)` every 500 ms with an empty text block and fresh `details.jobs` snapshots.\n- Final return is single-shot after a completion, timeout, abort, or immediate fast path.\n\nRead-only snapshot path:\n- Calling `job` with `list: true` returns a markdown summary of every job spawned by the calling agent (running + completed within retention) without waiting.\n\n## Flow\n1. `JobTool.createIf(...)` in `packages/coding-agent/src/tools/job.ts` only exposes the tool when `isBackgroundJobSupportEnabled(...)` returns true for either `async.enabled` or `bash.autoBackground.enabled`.\n2. `execute(...)` fetches `session.asyncJobManager`. If absent, it returns `Async execution is disabled; no background jobs are available.`\n3. `cancel` ids are processed first:\n - `manager.getJob(id)` missing → `not_found`.\n - existing job with `status !== \"running\"` → `already_completed`.\n - running job → `manager.cancel(id)`, which sets `job.status = \"cancelled\"`, aborts the controller, and schedules eviction.\n4. Polling mode is chosen with `const shouldPoll = requestedPollIds !== undefined || cancelIds.length === 0`:\n - only `cancel` present → return immediately, no wait.\n - explicit `poll`, or no args at all → proceed to watch jobs.\n5. Watch set resolution:\n - explicit `poll` → map ids through `manager.getJob(...)` and drop missing ones.\n - no `poll` and no `cancel` → `manager.getRunningJobs()`.\n6. Empty watch set returns immediately:\n - if cancellations happened, return snapshots for the cancelled ids that still exist.\n - else return either `No matching jobs found for IDs: ...` or `No running background jobs to wait for.`\n7. If every watched job is already non-running, `#buildResult(...)` returns immediately without waiting.\n8. Otherwise the tool waits on `Promise.race(...)` across:\n - every watched running job's `job.promise`,\n - a timeout promise for `async.pollWaitDuration`,\n - the tool-call abort signal when present.\n9. Before waiting, it calls `manager.watchJobs(watchedJobIds)`. This suppresses automatic completion delivery for those ids while they are being watched.\n10. If `onUpdate` exists, a 500 ms interval sends progress snapshots from `#snapshotJobs(...)`; one snapshot is emitted immediately before entering the race.\n11. In `finally`, the tool always calls `manager.unwatchJobs(...)`, clears the timeout, and stops the progress interval.\n12. `#buildResult(...)` deduplicates jobs, snapshots current manager state, then calls `manager.acknowledgeDeliveries(...)` for every non-running job in the result. That suppresses later automatic follow-up delivery for the same completions and removes queued deliveries for those ids.\n13. The final text groups jobs by non-running vs still-running state. A timeout is not an error path; it simply returns the current snapshot.\n\n## Modes / Variants\n- Poll all running jobs: call with neither `poll` nor `cancel`.\n- Poll explicit ids: call with `poll` only.\n- Cancel only: call with `cancel` only; cancellations happen and the tool returns immediately.\n- Cancel then poll: call with both. Cancellations are applied first, then the tool watches the remaining resolved `poll` ids.\n- Read-only inspection: call with `list: true` for the same snapshot data without waiting on completion.\n\nSpawn paths that produce jobs:\n- `packages/coding-agent/src/tools/bash.ts`\n - `async: true` always registers a `type: \"bash\"` job with `AsyncJobManager.register(...)` and returns a start message.\n - auto-background mode (`bash.autoBackground.enabled`) starts the same managed job path for non-PTY commands, waits up to `min(bash.autoBackground.thresholdMs, timeoutMs - 1000)`, and if the command is still running returns a background-job start result instead of inline command output.\n- `packages/coding-agent/src/task/index.ts`\n - when `async.enabled` is on, the chosen agent is not blocking, and `tasks.length > 0`, each task item is registered as a `type: \"task\"` job.\n\nLifecycle and exact state names:\n- Conceptual scheduling path: `pending` (only task-progress bookkeeping before work starts) → `running` → `completed` / `failed`; cancellation changes a running async job to `cancelled`.\n- Exact `AsyncJob.status` values in `packages/coding-agent/src/async/job-manager.ts`: `\"running\" | \"completed\" | \"failed\" | \"cancelled\"`.\n- Exact per-task progress values in `packages/coding-agent/src/task/types.ts`: `\"pending\" | \"running\" | \"completed\" | \"failed\" | \"aborted\"`.\n\n## Side Effects\n- Filesystem\n - None in `job.ts` itself.\n - Jobs being observed may already have written artifacts/results through their own tool runtimes.\n- Session state (transcript, memory, jobs, checkpoints, registries)\n - Reads and mutates `session.asyncJobManager` state.\n - `watchJobs(...)` / `unwatchJobs(...)` toggle delivery suppression for the watched ids.\n - `acknowledgeDeliveries(...)` marks completed ids as suppressed and removes queued deliveries for them.\n - `cancel(...)` aborts running jobs through each job's `AbortController`.\n- User-visible prompts / interactive UI\n - Polling emits periodic `onUpdate` snapshots every 500 ms.\n - Automatic job completion follow-ups are generated by `packages/coding-agent/src/sdk/session.ts` only for unsuppressed deliveries.\n- Background work / cancellation\n - Waiting uses a timeout plus optional tool-call abort signal.\n - Cancelling a job does not synchronously await teardown; it flips state, aborts, and returns control to the manager/job promise.\n\n## Limits & Caps\n- Poll wait duration comes from `async.pollWaitDuration` in `packages/coding-agent/src/config/settings-schema.ts`:\n - allowed values: `5s`, `10s`, `30s`, `1m`, `5m`\n - default: `30s`\n- Progress update cadence while polling: `PROGRESS_INTERVAL_MS = 500` in `packages/coding-agent/src/tools/job.ts`.\n- Async job retention default: `DEFAULT_RETENTION_MS = 5 * 60 * 1000` in `packages/coding-agent/src/async/job-manager.ts`.\n- Manager fallback max-running limit: `DEFAULT_MAX_RUNNING_JOBS = 15` in `packages/coding-agent/src/async/job-manager.ts`.\n- Session wiring clamps `async.maxJobs` to `1..100` before constructing the manager in `packages/coding-agent/src/sdk/session.ts`; settings default is `100` in `packages/coding-agent/src/config/settings-schema.ts`.\n- Async completion delivery retry backoff in `packages/coding-agent/src/async/job-manager.ts`:\n - base `500` ms\n - max `30_000` ms\n - jitter `< 200` ms\n - exponent capped at 8 doublings\n\n## Errors\n- Tool-disabled path is returned as normal text, not thrown: `Async execution is disabled; no background jobs are available.`\n- Polling a nonexistent id is not an exception:\n - with `poll` only, missing ids are dropped; if none remain the tool returns `No matching jobs found for IDs: ...`.\n - with `cancel`, each missing id is reported as `not_found` in `details.cancelled` and text.\n- Cancelling a non-running job is not an exception; it reports `already_completed` even if the actual status is `completed`, `failed`, or `cancelled`.\n- Tool-call abort during polling stops waiting and returns a final snapshot through `#buildResult(...)`; it does not cancel watched jobs.\n- Failures inside the underlying async work are stored on the job (`status: \"failed\"`, `errorText`) and reported in normal tool output, not rethrown by `job`.\n- Calling `list: true` against an empty manager returns a normal empty-list result rather than throwing; missing ids passed to `poll` are silently filtered.\n\n## Notes\n- `job` waits for the first watched running job to settle, not for all watched jobs. If others remain `running`, they are reported under `## Still Running`; the caller must invoke `job` again to continue waiting.\n- Delivery suppression is the key difference between snapshot and automatic delivery:\n - snapshots (`job` calls with `poll` or `list: true`) read current manager state;\n - follow-up delivery comes from `AsyncJobManager.#enqueueDelivery(...)` and `sdk.ts` `onJobComplete`;\n - watched or acknowledged ids are suppressed via `isDeliverySuppressed(...)`.\n- `manager.cancel(id)` sets `status = \"cancelled\"` before the underlying promise settles. The job function may later populate `resultText` or `errorText`; `job-manager.ts` preserves that text but does not transition the status away from `cancelled`.\n- Retention eviction removes the job record, suppression flags, and watch flag together. After eviction, both `job` calls and `list: true` snapshots behave as if the id never existed.\n",
|
|
120
122
|
"tools/locate.md": "# `locate`\n\nFind where behaviour lives by describing what the code does. Relevance is judged by Jev (TypeSafe), in the style of [jevgrep](https://github.com/dzhng/jevgrep), but inside SKC and using the stored TypeSafe key.\n\n- Source: `packages/coding-agent/src/tools/locate.ts` (tool), `packages/coding-agent/src/tools/locate-core.ts` (walk, outlines)\n- Prompt: `packages/coding-agent/src/prompts/tools/locate.md`\n- Setting: `locate.enabled` (Settings → Tools → Locate, on by default)\n\n## When it is offered\n\nOnly when `locate.enabled` is on **and** a TypeSafe key is stored (`/provider typesafe`). Without the hosted model every judgement would fall to an uncalibrated LLM, which costs more than the search saves, so the tool is simply absent.\n\n## Parameters\n\n| Name | Type | Notes |\n| --- | --- | --- |\n| `query` | string | What the code does, as a question or description |\n| `path` | string? | Directory to search, default the working directory. Filesystem root is refused. |\n| `limit` | number? | Most files to return, 1-40, default 12 |\n\n## How it searches\n\n1. **List** files under `path` with the native glob: `.gitignore` respected, hidden files skipped, lock/binary/media/map files dropped.\n2. **Walk folders.** A folder with at most 40 files is taken whole. A bigger one is split: its subfolders are sent to Jev in batches of 12, each shown as its path, file count, and up to 14 file names and 6 subfolder names. A subfolder is entered when it scores at least `max(0.35, 0.55 × best sibling score)`; the two best siblings above 0.2 are always entered, and so are the two folders whose names and file names share the most words with the query (Jev judges folders from names alone and sometimes undersells the obvious one). A failed request keeps its folders.\n3. **Judge files** in batches of 8, most promising folders first (a path that contains query words goes ahead within its folder). Each file is shown as its path and its **outline**: declaration lines only. When an outline is longer than 2,000 characters, declarations sharing words with the query are kept first.\n4. **Local keyword score.** Every listed file up to 512 KB is read on this machine and scored by the query words it contains (identifiers split into words, rarer words weigh more), comments and strings included. It is added to Jev's score at weight 0.3, orders files within the cap, adds the two best-scoring folders at each depth, and puts the twelve best files up for judgement even when their folder was not entered. None of this text is sent.\n5. **Compare the leaders.** The six best files are shown together in one choice question (\"which one most directly implements it?\"), and reordered by Jev's probability for each. Scored one at a time, near-equal files (0.62 vs 0.60) came out in near-random order; this step raised top-1 from 46% to 68% on the development set.\n6. **Return** files scoring 0.5 or more, then files from 0.3 marked `weak`, up to `limit`. When none reach 0.3, the three best are shown as leads.\n\nCeilings per call: 100 Jev requests plus one for the comparison, 480 judged files, folder depth 8, 8 requests in flight.\n\n## What is sent to TypeSafe\n\nThe question, folder paths and file names, and each candidate file's outline. The outline comes from the native structural summariser with every body and comment elided, plus the member lines of class-like bodies (methods and fields at the body's own indentation). For the 1-2% of files the parser rejects, a line-based fallback keeps top-level declarations and method signatures one indent level in. Lines inside block comments (`/* … */`, Rust `/*! … */`), Python docstrings, multi-line strings (including Rust `r#\"…\"#`), trailing `#`/`//` comments, lines that begin with a string literal, and statements (`return`, `assert`, `raise`, …) are dropped. An audit over all 15 benchmark repositories (73,508 outline lines) found no comment or string content; the 38 lines that do not look like code are type parameters and field declarations. From each kept line:\n\n- comments, imports, lone brackets and union/intersection member lines are dropped;\n- initialisers are cut: `const LIMIT = 42` is sent as `const LIMIT`, `private token = \"…\"` as `private token`. Function-valued initialisers keep their parameters, since those are the signature.\n\nFunction bodies, comments and literal values are never sent. Measured on `packages/coding-agent/src` (1,438 files, 17.4 MB), one search sent 290 KB: 10% of the judged files' source, 1.7% of the tree, about 72K Jev input tokens (about $0.003 at the listed $0.042/M).\n\n## Output\n\nA header with counts (folders and files judged, Jev requests, time), then ranked files, each with up to 12 outline lines as `L<line> <declaration>`. The result is a lead, not proof: it can miss files. Read the listed lines next.\n\n## Measured\n\nBenchmark on 15 public repositories (Python: requests, flask, httpx, fastapi, pydantic; TypeScript: hono, vite, zod, got; Go: gin, cobra, fzf; Rust: ripgrep, axum, clap), 292 questions. Each question is a real commit subject (maintenance and tooling commits dropped); the answer is the one to three non-test source files that commit changed, still present at `HEAD`. A hit is any answer file in the top k. Tuning used seven repositories (requests, httpx, hono, got, gin, ripgrep, axum); the other eight were run once, after tuning stopped.\n\nHeld-out repositories (154 questions), top-1 / top-3 / top-5 / top-10:\n\n| | locate | keyword grep over full text |\n| --- | --- | --- |\n| All | 51% / 73% / 78% / 86% | 27% / – / 58% / 69% |\n| Python (54) | 50% / 67% / 70% / 83% | 20% / – / 54% / 67% |\n| TypeScript (40) | 33% / 65% / 70% / 75% | 25% / – / 50% / 68% |\n| Go (40) | 70% / 88% / 93% / 100% | 43% / – / 80% / 88% |\n| Rust (20) | 55% / 80% / 85% / 90% | 15% / – / 40% / 45% |\n\nThe local keyword score raised top-5 from 70% to 78% and top-10 from 75% to 86% on the held-out set; top-1 stayed at 51%. Per search: about 46 Jev requests, 4.7 s, 5 KB returned. In large trees (vite, fastapi, pydantic) the per-call file cap is still reached in about a fifth of searches.\n\nCommit subjects are terse and sometimes name a module, so they are neither easier nor harder than a user's question in any uniform way; treat these as relative numbers.\n\n## Use something else when\n\nYou already know a name, path or exact string: `search` and `find` are faster and free.\n",
|