@kolisachint/hoocode-agent 0.5.41 → 0.5.43

package/dist/modes/interactive/websearch-warning.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The "websearch has no API key" startup notice.
+ *
+ * `websearch` works with no configuration at all, but the keyless default is
+ * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and
+ * the failure surfaces as a bad search rather than as a setup problem. So when
+ * the tool is active and no keyed backend is configured, the session says so
+ * once — the same shape as the Anthropic extra-usage notice, including the
+ * `/settings` switch that turns it off.
+ */
+import type { WarningSettings } from "../../core/settings-types.js";
+import { type WebtoolsSearchSettings } from "../../core/tools/webtools-shared.js";
+export declare const WEBSEARCH_API_KEY_TITLE = "Web search has no API key";
+export interface WebSearchApiKeyNoticeInput {
+    /** Tools the session actually exposes; the notice is pointless without `websearch`. */
+    activeToolNames: readonly string[];
+    /** Warning switches from settings (`warnings.websearchApiKey`). */
+    warnings: WarningSettings;
+    /** The `webtools.search` block, as the binary would read it. */
+    search?: WebtoolsSearchSettings;
+}
+export interface WebSearchApiKeyNotice {
+    title: string;
+    body: string[];
+}
+/**
+ * The notice to show, or undefined when there is nothing to say: the tool is
+ * off, a keyed backend is configured, the user pinned the keyless backend on
+ * purpose, or the warning is switched off.
+ *
+ * Pure, so the decision is testable without a TUI; the caller owns the
+ * once-per-session latch.
+ */
+export declare function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined;
+//# sourceMappingURL=websearch-warning.d.ts.map

package/dist/modes/interactive/websearch-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch-warning.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/websearch-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE/G,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,MAAM,WAAW,0BAA0B;IAC1C,uFAAuF;IACvF,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mEAAmE;IACnE,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,GAAG,SAAS,CAiB1G","sourcesContent":["/**\n * The \"websearch has no API key\" startup notice.\n *\n * `websearch` works with no configuration at all, but the keyless default is\n * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and\n * the failure surfaces as a bad search rather than as a setup problem. So when\n * the tool is active and no keyed backend is configured, the session says so\n * once — the same shape as the Anthropic extra-usage notice, including the\n * `/settings` switch that turns it off.\n */\n\nimport type { WarningSettings } from \"../../core/settings-types.js\";\nimport { resolveWebSearchCredentials, type WebtoolsSearchSettings } from \"../../core/tools/webtools-shared.js\";\n\nexport const WEBSEARCH_API_KEY_TITLE = \"Web search has no API key\";\n\nexport interface WebSearchApiKeyNoticeInput {\n\t/** Tools the session actually exposes; the notice is pointless without `websearch`. */\n\tactiveToolNames: readonly string[];\n\t/** Warning switches from settings (`warnings.websearchApiKey`). */\n\twarnings: WarningSettings;\n\t/** The `webtools.search` block, as the binary would read it. */\n\tsearch?: WebtoolsSearchSettings;\n}\n\nexport interface WebSearchApiKeyNotice {\n\ttitle: string;\n\tbody: string[];\n}\n\n/**\n * The notice to show, or undefined when there is nothing to say: the tool is\n * off, a keyed backend is configured, the user pinned the keyless backend on\n * purpose, or the warning is switched off.\n *\n * Pure, so the decision is testable without a TUI; the caller owns the\n * once-per-session latch.\n */\nexport function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined {\n\tif (input.warnings.websearchApiKey === false) return undefined;\n\tif (!input.activeToolNames.includes(\"websearch\")) return undefined;\n\n\tconst credentials = resolveWebSearchCredentials(input.search);\n\tif (credentials.configured || credentials.explicitKeyless) return undefined;\n\n\treturn {\n\t\ttitle: WEBSEARCH_API_KEY_TITLE,\n\t\t// Two lines, like the Anthropic notice: what is wrong and the one setting\n\t\t// that fixes it. The other backends and the settings.json block are in\n\t\t// the docs — a startup notice is not the place to list them.\n\t\tbody: [\n\t\t\t\"Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.\",\n\t\t\t\"Turn off in /settings → Web search API key.\",\n\t\t],\n\t};\n}\n"]}

package/dist/modes/interactive/websearch-warning.js

@@ -0,0 +1,40 @@
+/**
+ * The "websearch has no API key" startup notice.
+ *
+ * `websearch` works with no configuration at all, but the keyless default is
+ * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and
+ * the failure surfaces as a bad search rather than as a setup problem. So when
+ * the tool is active and no keyed backend is configured, the session says so
+ * once — the same shape as the Anthropic extra-usage notice, including the
+ * `/settings` switch that turns it off.
+ */
+import { resolveWebSearchCredentials } from "../../core/tools/webtools-shared.js";
+export const WEBSEARCH_API_KEY_TITLE = "Web search has no API key";
+/**
+ * The notice to show, or undefined when there is nothing to say: the tool is
+ * off, a keyed backend is configured, the user pinned the keyless backend on
+ * purpose, or the warning is switched off.
+ *
+ * Pure, so the decision is testable without a TUI; the caller owns the
+ * once-per-session latch.
+ */
+export function websearchApiKeyNotice(input) {
+    if (input.warnings.websearchApiKey === false)
+        return undefined;
+    if (!input.activeToolNames.includes("websearch"))
+        return undefined;
+    const credentials = resolveWebSearchCredentials(input.search);
+    if (credentials.configured || credentials.explicitKeyless)
+        return undefined;
+    return {
+        title: WEBSEARCH_API_KEY_TITLE,
+        // Two lines, like the Anthropic notice: what is wrong and the one setting
+        // that fixes it. The other backends and the settings.json block are in
+        // the docs — a startup notice is not the place to list them.
+        body: [
+            "Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.",
+            "Turn off in /settings → Web search API key.",
+        ],
+    };
+}
+//# sourceMappingURL=websearch-warning.js.map

package/dist/modes/interactive/websearch-warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch-warning.js","sourceRoot":"","sources":["../../../src/modes/interactive/websearch-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,2BAA2B,EAA+B,MAAM,qCAAqC,CAAC;AAE/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAgBnE;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC,EAAqC;IAC3G,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC/D,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnE,MAAM,WAAW,GAAG,2BAA2B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,eAAe;QAAE,OAAO,SAAS,CAAC;IAE5E,OAAO;QACN,KAAK,EAAE,uBAAuB;QAC9B,0EAA0E;QAC1E,uEAAuE;QACvE,+DAA6D;QAC7D,IAAI,EAAE;YACL,2FAA2F;YAC3F,+CAA6C;SAC7C;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * The \"websearch has no API key\" startup notice.\n *\n * `websearch` works with no configuration at all, but the keyless default is\n * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and\n * the failure surfaces as a bad search rather than as a setup problem. So when\n * the tool is active and no keyed backend is configured, the session says so\n * once — the same shape as the Anthropic extra-usage notice, including the\n * `/settings` switch that turns it off.\n */\n\nimport type { WarningSettings } from \"../../core/settings-types.js\";\nimport { resolveWebSearchCredentials, type WebtoolsSearchSettings } from \"../../core/tools/webtools-shared.js\";\n\nexport const WEBSEARCH_API_KEY_TITLE = \"Web search has no API key\";\n\nexport interface WebSearchApiKeyNoticeInput {\n\t/** Tools the session actually exposes; the notice is pointless without `websearch`. */\n\tactiveToolNames: readonly string[];\n\t/** Warning switches from settings (`warnings.websearchApiKey`). */\n\twarnings: WarningSettings;\n\t/** The `webtools.search` block, as the binary would read it. */\n\tsearch?: WebtoolsSearchSettings;\n}\n\nexport interface WebSearchApiKeyNotice {\n\ttitle: string;\n\tbody: string[];\n}\n\n/**\n * The notice to show, or undefined when there is nothing to say: the tool is\n * off, a keyed backend is configured, the user pinned the keyless backend on\n * purpose, or the warning is switched off.\n *\n * Pure, so the decision is testable without a TUI; the caller owns the\n * once-per-session latch.\n */\nexport function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined {\n\tif (input.warnings.websearchApiKey === false) return undefined;\n\tif (!input.activeToolNames.includes(\"websearch\")) return undefined;\n\n\tconst credentials = resolveWebSearchCredentials(input.search);\n\tif (credentials.configured || credentials.explicitKeyless) return undefined;\n\n\treturn {\n\t\ttitle: WEBSEARCH_API_KEY_TITLE,\n\t\t// Two lines, like the Anthropic notice: what is wrong and the one setting\n\t\t// that fixes it. The other backends and the settings.json block are in\n\t\t// the docs — a startup notice is not the place to list them.\n\t\tbody: [\n\t\t\t\"Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.\",\n\t\t\t\"Turn off in /settings → Web search API key.\",\n\t\t],\n\t};\n}\n"]}

package/docs/settings.md

@@ -74,15 +74,20 @@ Set `HOOCODE_SKIP_VERSION_CHECK=1` to disable the HooCode version update check.
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
+| `warnings.websearchApiKey` | boolean | `true` | Show a warning when `websearch` is enabled with no search API key, so it falls back to keyless DuckDuckGo |
 
 ```json
 {
   "warnings": {
-    "anthropicExtraUsage": false
+    "anthropicExtraUsage": false,
+    "websearchApiKey": false
   }
 }
 ```
 
+Both warnings are shown once per session in the TUI and can also be toggled from
+`/settings` → Warnings.
+
 ### Compaction
 
 | Setting | Type | Default | Description |
@@ -329,6 +334,7 @@ there.
 |---------|------|---------|-------------|
 | `enableWebTools` | boolean | `false` | Enable `webfetch` + `websearch` (network access). Needs the `webtools` binary. |
 | `webtools.timeoutSecs` | number | `15` | Per-request timeout in seconds, clamped 1–120. Wins over `HOOCODE_WEBTOOLS_TIMEOUT`. |
+| `webtools.search` | object | — | Search backend and credentials, read by the `webtools` binary itself. See [Web search providers](#web-search-providers). |
 | `enableEmbsearchTools` | boolean | `true` | Build and fuse the semantic index into `search`. Set false to run `search` lexical-only. `grep`/`find` are unaffected. |
 | `embsearchBinaryPath` | string | — | Explicit path to the `embsearch` binary. Default: resolve from `PATH`. |
 | `embsearchThresholdBytes` | number | `0` | Minimum indexable source bytes before a repo is embedded. `0` indexes every repo. |
@@ -346,6 +352,49 @@ Environment variables:
 On Android/Termux the published Linux builds do not run; install with
 `pkg install <name>` instead.
 
+#### Web search providers
+
+`websearch` needs no configuration: it defaults to keyless DuckDuckGo Lite.
+That backend is scraped HTML, though — rate-limited hard, and it can fail
+outright — so when search reliability matters, point it at a backend with an
+actual API contract. With none configured, the TUI says so once per session
+(see [`warnings.websearchApiKey`](#warnings)).
+
+The `webtools` binary reads its own `webtools` key out of the user-level
+`~/.hoocode/settings.json`, using its own (snake_case) key names. HooCode never
+writes this block; it only reads it to tell whether a keyed backend exists. Put
+it in the user-level file — a project `.hoocode/settings.json` is not read by the
+binary, and a file holding credentials is worth keeping out of a working tree.
+
+```json
+{
+  "webtools": {
+    "search": {
+      "provider": "brave",
+      "fallback": "duckduckgo",
+      "providers": {
+        "brave": { "api_key": "..." },
+        "tavily": { "api_key": "..." },
+        "searxng": { "base_url": "https://searx.internal" }
+      }
+    }
+  }
+}
+```
+
+Environment variables win over the file, so a key can stay out of it entirely:
+
+| Variable | Effect |
+|---|---|
+| `WEBTOOLS_SEARCH_PROVIDER` | Backend to use: `duckduckgo` (default), `brave`, `tavily`, `searxng`. Pin `duckduckgo` to accept the keyless backend and silence the warning. |
+| `WEBTOOLS_SEARCH_FALLBACK` | Backend tried when the primary fails; `none` disables the fallback. |
+| `WEBTOOLS_BRAVE_API_KEY`, `BRAVE_API_KEY` | Brave Search key. |
+| `WEBTOOLS_TAVILY_API_KEY`, `TAVILY_API_KEY` | Tavily key. Returns cleaned page content, so a search often answers without a follow-up `webfetch`. |
+| `WEBTOOLS_SEARXNG_URL`, `WEBTOOLS_SEARXNG_API_KEY` | Self-hosted SearXNG endpoint (and optional key), for networks where the public APIs are unreachable. |
+
+Every result records the backend that answered it, so a fallback to the scraped
+backend is never silent.
+
 ### Resources
 
 These settings define where to load extensions, skills, prompts, and themes from.
@@ -408,7 +457,8 @@ See [packages.md](packages.md) for package management details.
   },
   "enabledModels": ["claude-*", "gpt-4o"],
   "warnings": {
-    "anthropicExtraUsage": true
+    "anthropicExtraUsage": true,
+    "websearchApiKey": true
   },
   "packages": ["hoocode-skills"]
 }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.3.41",
+	"version": "0.3.43",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.3.41",
+	"version": "0.3.43",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-sandbox",
 	"private": true,
-	"version": "0.3.41",
+	"version": "0.3.43",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-with-deps",
 	"private": true,
-	"version": "0.3.41",
+	"version": "0.3.43",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kolisachint/hoocode-agent",
-	"version": "0.5.41",
+	"version": "0.5.43",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"hoocodeConfig": {
@@ -50,9 +50,9 @@
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@kolisachint/hoocode-agent-core": "^0.5.41",
-		"@kolisachint/hoocode-ai": "^0.5.41",
-		"@kolisachint/hoocode-tui": "^0.5.41",
+		"@kolisachint/hoocode-agent-core": "^0.5.43",
+		"@kolisachint/hoocode-ai": "^0.5.43",
+		"@kolisachint/hoocode-tui": "^0.5.43",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",

package/templates/agents/code-review.md

@@ -0,0 +1,61 @@
+---
+name: code-review
+description: |
+  Use this subagent when:
+  - Reviewing a diff, branch, or files for defects before merge
+  - The user asks for a review, a second pass, or what they missed
+  - Findings are wanted without spending parent context on every changed file
+
+  DO NOT use for:
+  - Applying the fixes (this agent reports; the parent decides)
+  - Hunting for security vulnerabilities specifically (use security-review)
+
+  Output: Ranked findings, each with path:line, the defect, and how it fails.
+  Cost: Medium (reads the full diff and surrounding code)
+  Isolation: Read-only; can run in parallel with other review tasks
+tools: read, bash, grep, find, ls
+model: capable
+background: true
+---
+You are a code-review agent running inside hoocode. You find defects in changed
+code and report them. You never edit files. You run in an isolated context and
+cannot see the parent conversation, so state findings in full rather than
+referring back to a discussion you cannot read.
+
+Scope:
+- Do not create, modify, or delete files.
+- Use bash for read-only git commands (`git diff`, `git log`, `git show`) to
+  establish what changed. Do not commit, push, stash, or check out.
+- Review what the caller named. If they named nothing, review the working tree
+  diff, then the branch against its base.
+
+Method:
+1. Establish the diff. Read every changed hunk before forming an opinion.
+2. Read enough surrounding code to know whether a hunk is actually wrong. A
+   line that looks suspicious in isolation is usually fine in context.
+3. For each candidate finding, construct the concrete failure: the input or
+   state that triggers it, and the wrong output or crash that results. If you
+   cannot construct one, it is not a finding.
+4. Rank what survives by severity.
+
+What counts as a finding:
+- Correctness: logic that produces a wrong result, a crash, unhandled errors,
+  off-by-one, wrong operator, a case the code does not cover.
+- Contract violations: a caller that does not match the callee's expectations,
+  a type narrowed incorrectly, an invariant the change breaks.
+- Reuse: the change hand-rolls something the codebase already provides.
+- Efficiency: work repeated in a loop that belongs outside it, an avoidable
+  quadratic, a re-read of something already in memory.
+
+What does not:
+- Style, formatting, or naming the linter does not flag.
+- Restating what the code does without saying what is wrong with it.
+- Speculative hardening for inputs the code cannot receive.
+
+Guidance:
+- Verify before reporting. A confident wrong finding costs the caller more than
+  a missed one, because they have to read the code to disprove it.
+- Report as a ranked list: `path:line`, one sentence naming the defect, then the
+  failure case. No preamble, no summary of the change, no tool logs.
+- If nothing survives verification, say so plainly. An empty review is a
+  legitimate result.

package/templates/agents/security-review.md

@@ -0,0 +1,69 @@
+---
+name: security-review
+description: |
+  Use this subagent when:
+  - Reviewing changes for vulnerabilities before merge or release
+  - The change touches auth, input parsing, paths, subprocesses, or secrets
+  - The user asks for a security review or audit of pending work
+
+  DO NOT use for:
+  - General correctness and quality review (use code-review)
+  - Applying the fixes (this agent reports; the parent decides)
+
+  Output: Findings ranked by severity, each with path:line, the attack, and the
+  fix.
+  Cost: Medium (reads the diff and traces untrusted input)
+  Isolation: Read-only; can run in parallel with other review tasks
+tools: read, bash, grep, find, ls
+model: capable
+background: true
+---
+You are a security-review agent running inside hoocode. You find vulnerabilities
+in changed code and report them. You never edit files. You run in an isolated
+context and cannot see the parent conversation, so state findings in full rather
+than referring back to a discussion you cannot read.
+
+Scope:
+- Do not create, modify, or delete files.
+- Use bash for read-only git commands (`git diff`, `git log`, `git show`) to
+  establish what changed. Do not commit, push, stash, or check out.
+- Review what the caller named. If they named nothing, review the working tree
+  diff, then the branch against its base.
+
+Method:
+1. Establish the diff, then identify every point where the change accepts input
+   it does not control: arguments, environment, files, network responses, tool
+   output, model output.
+2. Trace each one to where it is used. A vulnerability is a path from untrusted
+   input to a dangerous operation, so follow the path rather than pattern
+   matching on the operation.
+3. For each candidate, construct the attack: what an attacker supplies, what
+   they gain. If you cannot construct one, it is not a finding.
+4. Rank what survives by severity, worst first.
+
+Where to look hardest:
+- Command execution: shell strings built from input, argument arrays that can be
+  injected, a path that reaches an interpreter.
+- Path handling: traversal via `..` or absolute paths, symlinks, writes outside
+  an intended root.
+- Secrets: credentials logged, embedded in errors, written to disk, sent to a
+  provider that does not need them.
+- Deserialization and parsing: untrusted JSON, YAML, or archives fed to a parser
+  that can execute or allocate unboundedly.
+- Authorization: a check that can be bypassed, a permission gate the change
+  routes around, a default that fails open.
+- Injection into generated content: HTML, SQL, or prompt text assembled from
+  input without escaping.
+
+What does not count:
+- A theoretical issue in code the change did not touch and does not reach.
+- Missing hardening with no reachable attack path.
+- Dependency advisories the change neither introduces nor exercises.
+
+Guidance:
+- Verify reachability before reporting. An unreachable finding wastes the
+  caller's time and erodes trust in the review.
+- Report as a severity-ranked list: `path:line`, the attack in one or two
+  sentences, then the fix. No preamble, no tool logs.
+- Where a fix has a safer and a more convenient form, name the safer one.
+- If nothing survives verification, say so plainly.

package/templates/skills/artifact-design/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: artifact-design
+description: Build a self-contained HTML visual written to disk — page, report, dashboard, mockup, diagram, or poster. Load before the first line of markup or CSS whenever something has to look right, or a redesign is asked for. Not for app code the project's own design system already governs.
+allowed-tools: read, write, edit, grep, find, ls
+---
+
+# Designing a visual
+
+hoocode writes visuals as one self-contained `.html` file on disk. There is no
+host, no CSP, and no gallery: fonts and libraries may come from a CDN or from
+local files, and the page is yours to lay out however the subject demands. The
+constraint that remains is the only one that ever mattered — it has to be good.
+
+Not for a canvas extension. A canvas serves a live page from its own loopback
+server, under constraints that contradict half of this file, and `/new-canvas`
+points at `../canvas-design/SKILL.md` for it.
+
+## First, read the request
+
+Decide the treatment, not whether to design. Every visual gets real typographic
+hierarchy, considered spacing, and a deliberate palette. What varies is how far
+past that you go.
+
+- **Utilitarian** — a report, a plan, a status page, a diagram. Most requests.
+  Make it clean and well-composed. Skip the oversized hero. Keep flourishes few.
+- **Editorial** — a landing page, a poster, something the user will show other
+  people. Take a real point of view and one deliberate risk.
+
+When unsure, build the well-composed version. A restrained page is never wrong;
+an over-designed one sometimes is.
+
+## Honor what already exists
+
+Look before you invent. If the repo has a design system — a tokens file, a
+theme, CSS variables, an existing stylesheet, a brand section in a project
+context file — use it. Precedence is always:
+
+1. What the user asked for, in their words
+2. The project's existing system
+3. Your own choices
+
+Your choices fill gaps. They never override the first two.
+
+## Write the plan before the markup
+
+This is the part that does the work. Before any code, write down:
+
+- **Color** — 4 to 6 named hex values. Name them by role (`ink`, `ground`,
+  `accent`, `muted`), not by hue.
+- **Type** — at least two faces with distinct jobs: one with character for
+  display, one comfortable for body text, and a third for data or captions if
+  the content needs it. Name the fallback stack for each.
+- **Layout** — the structural idea in one or two sentences.
+
+Then build from the plan and derive every color and type decision from it. A
+page assembled without a plan reads as assembled without a plan.
+
+## Fundamentals
+
+**Ground it in the subject.** One concrete subject, one audience, one job for
+the page. Distinctive choices come from the subject's own world — its materials,
+its vocabulary, how people in it actually talk. Use real content throughout.
+Never lorem, never placeholder rows.
+
+**Type carries the page,** including when the page is not about type. Keep
+running text near 65 characters wide. Set a scale and stay on it. Give headings
+`text-wrap: balance`, give body text line-height room, give uppercase labels a
+little letter-spacing. Always declare a real fallback stack — a silent fallback
+is the most common way a good design ships looking wrong.
+
+**Pick the neutrals.** A pure mid-grey reads as unconsidered. Bias the greys
+slightly toward the accent hue and they read as chosen. Pure white and near-black
+are fine grounds when the subject wants them; the point is that you decided.
+
+**Let layout do the spacing.** Flex or grid with `gap`, not per-element margins
+that collapse or double unpredictably. Wide content — tables, code blocks,
+diagrams — gets its own `overflow-x: auto` container so the page body never
+scrolls sideways. Use `font-variant-numeric: tabular-nums` wherever digits line
+up in a column.
+
+**Design both themes.** A local page sees only `prefers-color-scheme`, so this
+is simpler here than on a hosted target: define the complete palette as custom
+properties on `:root`, redefine only those properties inside
+`@media (prefers-color-scheme: dark)`, and style every component through the
+properties. Never give a color its only definition inside the media block — that
+is how a page ends up rendering one theme's text on the other theme's ground.
+Set an explicit `background` on `body`. Give the second theme the same attention
+as the first rather than inverting it mechanically; check that the accent still
+works on both grounds. A page that deliberately commits to one visual world may
+stay single-theme, but then paint every color explicitly so it holds either way.
+
+**Structure should encode something true.** Numbered markers, eyebrows,
+dividers, and section labels are information, not decoration. Number things only
+when the order actually matters to the reader.
+
+**When it is a UI, not a document,** the craft shifts from typography to
+information design. A dashboard is scanned, not read. Put the summary above the
+detail. Encode state in form as well as in number — a pill, a chip, a severity
+stripe — so what needs attention is visible at a glance. Semantic color (good,
+warning, critical) is a separate system from your accent and does not count as
+using it. Anything interactive should look interactive.
+
+## Avoid the generated look
+
+Machine-generated design keeps landing on the same handful of looks. When the
+user has specified a direction, follow it exactly, including if it is one of
+these. When nothing is specified, do not spend the freedom here:
+
+- Warm cream ground, serif display face, terracotta accent
+- Near-black ground with a single acid-green or vermilion pop
+- Hairline rules and dense columns imitating a broadsheet
+- Purple-to-blue gradient hero on white
+- Inter or Space Grotesk chosen as the safe default
+- Emoji as section markers
+- Everything centered
+- Uniform large corner radii on every surface
+- A colored accent rail down the side of every card
+
+## Words are design material
+
+Write from the reader's side of the screen. Name things the way they would name
+them, not the way the system is built. Active voice. A control says exactly what
+it does, and the confirmation matches it. Errors say what went wrong and what to
+do about it. Specific beats clever.
+
+Give the page a real `<title>` — a short, specific noun phrase, not a category
+label and not a name with an explainer bolted on after a dash.
+
+## Libraries, and why the answer is usually none
+
+A hosted page and a file on disk fail differently, and that decides this. A
+hosted page is always viewed online, so a CDN dependency is free. A file gets
+moved, attached to mail, and opened on a laptop in a tunnel — and there a
+runtime dependency does not degrade, it collapses. Tailwind from a CDN with no
+network is an unstyled document. React from a CDN with no network is a blank
+one.
+
+So the default is no runtime dependency at all. Write plain CSS; modern CSS has
+custom properties, grid, `clamp()`, and container queries, and a page that needs
+a utility framework to be laid out usually needs a clearer layout instead.
+
+There is no build step here and nothing bundles this file, so a framework that
+expects one — Vite, a JSX pipeline, anything importing bare module specifiers —
+is not an option regardless.
+
+When a library genuinely earns its place, and that is mostly charting or syntax
+highlighting rather than layout:
+
+- Inline it into the file if its licence permits, and the page stays whole.
+- Otherwise pin an exact version, give the feature a readable fallback for when
+  the script does not load, and tell the user the page needs network.
+
+Webfonts are the one dependency that degrades gracefully, because a real
+fallback stack keeps the page readable when the link fails. Use one, and always
+declare the stack.
+
+## Build cleanly
+
+- Watch selector specificity. Type-level and element-level selectors fighting
+  over the same padding is how spacing silently comes undone.
+- Close every non-void element and double-quote every attribute.
+- Give keyboard focus a visible state.
+- Respect `prefers-reduced-motion`.
+- For generative or decorative graphics, reach for Canvas or WebGL rather than
+  hand-authoring long SVG path data.
+- Before finishing, scan the stylesheet for any color declared only inside a
+  media query.
+
+## Delivering it
+
+Write one self-contained `.html` file. Inline the page's own CSS and JS; embed
+small assets as data URIs so the file survives being moved or sent to someone.
+
+Put it where the user would expect it — alongside the data it visualizes, or in
+the directory they named. Then give them the path as a markdown link with a
+`file://` URL:
+
+```
+[tokens.html](file:///abs/path/to/tokens.html)
+```
+
+hoocode's markdown renderer turns that into an OSC 8 hyperlink wherever the
+terminal supports one, so it is clickable in kitty, iTerm2, WezTerm and others,
+and still readable as plain text everywhere else. Offer to open it rather than
+opening it unasked.
+
+Canvas is not a viewer for this. `/canvas` hosts canvas extensions — a directory
+with an `extension.mjs` speaking the canvas JSON-RPC protocol — and `/canvas
+open` takes an extension id, not a file path. A page you can hand someone is a
+file; reach for `/new-canvas` only when the user wants a live surface the agent
+can call typed actions on, which is a different and larger job than a visual.