tarsk 0.6.87 → 0.6.89

package/README.md

@@ -1,20 +1,22 @@
 # Tarsk CLI
 
-[Tarsk](https://tarsk.io) is an AI coding workspace for working with Git repositories in isolated threads. Each thread gets its own working copy, so you can explore ideas, run agents, review changes, and manage project work without disturbing your main branch.
+[Tarsk](https://tarsk.io) is an AI coding and knowledge workspace for working with Git repositories in isolated threads. Each thread gets its own working copy, so you can explore ideas, run agents, review changes, and manage project work without disturbing your main branch.
 
-The CLI starts a local Bun-powered server that serves the [Tarsk](https://tarsk.io) app and exposes the API for repository management, agent execution, and project workflows.
+The CLI starts a local Bun-powered server that serves the [Tarsk](https://tarsk.io) app and exposes the API for repository management, agent execution, and project workflows. The same server powers the macOS desktop app (Electrobun).
 
 ## Features
 
 - **Projects** — Connect an existing Git repository, open a local folder, or scaffold a new app from a template.
 - **Threads** — Create multiple isolated working copies per project for parallel experiments.
 - **AI agents** — Chat with agents that can read and modify code inside a thread, with diff review before accepting changes.
+- **Goals** — Run long-lived objectives with `/goal` across verified rounds and fresh context.
 - **Tasks** — Plan work in the Tasks view and jump into threads from tasks.
 - **Providers and models** — Configure AI providers, models, and per-project model aliases.
 - **MCP servers** — Attach Model Context Protocol servers for extended agent tooling.
 - **Rules, skills, and slash commands** — Customize agent behavior with project rules, bundled skills, and reusable commands.
 - **Git workflows** — Inspect status, review diffs, create commits, and open pull requests from the UI.
-- **Browser and terminal** — Run project commands, open dev servers in an embedded browser, and use integrated terminals.
+- **Slack** — Bind channels to projects and drive Tarsk from Slack (Socket Mode).
+- **Browser and terminal** — Run project commands, open dev servers in an embedded browser (desktop), and use integrated terminals.
 
 ## Quick start
 
@@ -32,14 +34,18 @@ To always use the latest published version:
 npx tarsk@latest
 ```
 
-You can also download the macOS desktop app from [tarsk.io](https://tarsk.io/#download). The desktop app bundles its own runtime and does not require Node.js.
+You can also download the macOS desktop app from [tarsk.io](https://tarsk.io/#download). The desktop app bundles its own runtime and does not require Node.js. Closing the window keeps the server running; quit from the menu bar tray.
 
 ## CLI options
 
-| Flag       | Description                                                                                                                                                              |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Flag | Description |
+| ---- | ----------- |
 | `--server` | Start the API server only. Do not open a browser tab. Useful for headless operation, remote access, or when another client (desktop app, mobile) connects to the server. |
-| `--debug`  | Enable verbose logging. Runs the server on port **462** instead of **641**.                                                                                              |
+| `--debug` | Enable verbose logging. Runs the server on port **462** instead of **641**. |
+| `--port <n>` | Server port in normal mode (sets `PORT`; default **641**). Ignored when `--debug` is set. |
+| `--open` | Open the browser even when `--server` is set. |
+| `--data-dir <path>` | Override the data directory (sets `TARSK_DATA_DIR`). |
+| `--assets-dir <path>` | Override companion server assets (`public/`, bundled skills, etc.; sets `TARSK_ASSETS_DIR`). |
 
 Examples:
 
@@ -47,41 +53,74 @@ Examples:
 npx tarsk --server          # headless server
 npx tarsk --debug           # troubleshoot with full logs
 npx tarsk --server --debug  # headless server with verbose logging
+npx tarsk --port 3000       # custom port (normal mode)
 ```
 
 ### Environment variables
 
-| Variable | Description                                                                                           |
-| -------- | ----------------------------------------------------------------------------------------------------- |
-| `PORT`   | Server port in normal mode (default: `641`). Ignored when `--debug` is set (debug always uses `462`). |
+| Variable | Description |
+| -------- | ----------- |
+| `PORT` | Server port in normal mode (default: `641`). Ignored when `--debug` is set (debug always uses `462`). |
+| `TARSK_APP_SUPPORT_DIR` | Root application support directory (logs, `port.json`, default layout). |
+| `TARSK_DATA_DIR` | Data directory (defaults to `<appSupport>/data`). Same effect as `--data-dir`. |
+| `TARSK_ASSETS_DIR` | Directory with bundled server assets. Same effect as `--assets-dir`. |
+| `MODE` | Set to `development` when running from the monorepo (`bun run web`); suppresses auto-open unless `--open` is passed. |
 
 If the default port is already in use, Tarsk tries the next available port and prints the URL it bound to.
 
 ## System requirements
 
-| Requirement                | Notes                                                                        |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| **git**                    | Required. Tarsk uses git to clone repositories and manage branches.          |
-| **Node.js 18+** or **Bun** | Required for `npx tarsk`.                                                    |
-| **gh CLI** (optional)      | Needed for creating GitHub repositories and pull requests from within Tarsk. |
+| Requirement | Notes |
+| ----------- | ----- |
+| **git** | Required. Tarsk uses git to clone repositories and manage branches. |
+| **Node.js 18+** or **Bun** | Required for `npx tarsk`. |
+| **gh CLI** (optional) | Needed for creating GitHub repositories and pull requests from within Tarsk. |
+
+Tarsk checks for `git` during onboarding on first launch and surfaces a warning with a download link if it is missing.
 
 ## Where data is stored
 
-All Tarsk data lives in your user data directory:
+All Tarsk data lives under your application support directory:
+
+| Platform | Default path |
+| -------- | ------------ |
+| macOS | `~/Library/Application Support/Tarsk/` |
+| Linux / Windows (CLI) | Same path under your home directory unless you override it (see below). |
 
-| Platform | Path                                   |
-| -------- | -------------------------------------- |
-| macOS    | `~/Library/Application Support/Tarsk/` |
-| Windows  | `%APPDATA%\Tarsk\`                     |
-| Linux    | `~/.config/Tarsk/`                     |
+The desktop app and CLI share these defaults. Set `TARSK_APP_SUPPORT_DIR` to move the whole tree (logs, `port.json`, and `data/`). Use `--data-dir` or `TARSK_DATA_DIR` to relocate only the `data/` folder. On Linux or Windows, set `TARSK_APP_SUPPORT_DIR` if you want a conventional path such as `~/.config/Tarsk`.
 
-Inside this directory:
+Inside the application support directory:
 
-- `tarsk.db` — SQLite database (projects, threads, conversations, settings)
-- `data/{threadId}/` — one directory per thread, containing the full git working copy for that thread
+- `data/tarsk.db` — SQLite database (projects, threads, conversations, settings)
+- `data/{repo-slug}/` — one directory per thread, each a full git working copy (for example `org-repo` from `https://github.com/org/repo`, with `-1`, `-2`, … when names collide)
+- `port.json` — active server port (written when the server starts)
 
 Each thread is a real, independent filesystem copy of your repository.
 
+## Remote access
+
+To use Tarsk from another device, sign in and enable **Mobile & Network Access** in **Settings → Remote Access**. Tarsk provisions a public address on tarsk.net; visitors must sign in as the same account. Restart Tarsk after changing this setting. See [Remote Access](https://tarsk.io/docs/settings/remote-machines/) in the product docs.
+
+## Developing from the monorepo
+
+From the repository root, see [README.md](../README.md) for full monorepo setup, build order, and `check:all`.
+
+Common workflows inside `cli/`:
+
+| Command | Purpose |
+| ------- | ------- |
+| `bun run web` | Run the server in development mode (same as root `bun run dev:cli`). |
+| `bun run dev` | Build frontend assets and launch the Electrobun desktop app in dev mode. |
+| `bun run dev:web` | Debug API on **462** plus Vite on **8100** (hot reload). |
+| `bun run build` | Production desktop build (codesigned when configured). |
+| `bun run build:unsigned` | Desktop build without codesign/notarize (CI and sandboxes). |
+| `bun run build:npm` | Server bundle only (published `npx tarsk` artifact). |
+| `bun run test` | CLI tests (`vp test run`, not bare `bun test`). |
+
+Implementation notes for contributors: [agents.md](agents.md) and [AGENTS.md](../AGENTS.md).
+
 ## Documentation
 
 - [tarsk.io/docs](https://tarsk.io/docs) — product documentation
+- [Installation](https://tarsk.io/docs/getting-started/installation/) — flags, data paths, and requirements
+- [README.md](../README.md) — monorepo layout and development

package/dist/bundled-skills/email-me/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: email-me
+description: Use when the user asks "email me".
+version: 1.0.0
+tools:
+  - email_me
+---
+# Email me
+
+Sends an email to the signed-in Tarsk user.
+
+- Put the information the user wants into `body`. Keep `subject` short.
+- Call `email_me` once, then report its answer.
+- When it reports that no one is signed in, ask the user to log in to Tarsk.
+  Do not call the tool again until the user is signed in.

package/dist/bundled-skills/email-me/scripts/__tests__/email_me.test.js

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { execute } from "../email_me.js";
+
+function contextReturning(result) {
+  const calls = [];
+  return {
+    calls,
+    email: {
+      async sendToSelf(message) {
+        calls.push(message);
+        return result;
+      },
+    },
+  };
+}
+
+void test("asks the user to log in to Tarsk when no account is signed in", async () => {
+  const context = contextReturning({ status: "not-signed-in" });
+
+  const result = await execute({ body: "The build is green." }, context);
+
+  assert.match(result.content[0].text, /log in to Tarsk/i);
+  assert.equal(context.calls.length, 1);
+});
+
+void test("sends the requested subject and body and names the address", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  const result = await execute(
+    { subject: "Status", body: "The build is green." },
+    context,
+  );
+
+  assert.deepEqual(context.calls, [{ subject: "Status", body: "The build is green." }]);
+  assert.match(result.content[0].text, /owner@example\.com/);
+});
+
+void test("defaults the subject when none is given", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  await execute({ body: "The build is green." }, context);
+
+  assert.equal(context.calls[0].subject, "Message from Tarsk");
+});
+
+void test("reports a failed send with the service message", async () => {
+  const context = contextReturning({ status: "failed", message: "rate limited" });
+
+  const result = await execute({ body: "The build is green." }, context);
+
+  assert.match(result.content[0].text, /rate limited/);
+  assert.equal(context.calls.length, 1);
+});
+
+void test("refuses an empty body without sending", async () => {
+  const context = contextReturning({ status: "sent", to: "owner@example.com" });
+
+  const result = await execute({ body: "   " }, context);
+
+  assert.match(result.content[0].text, /body/i);
+  assert.equal(context.calls.length, 0);
+});

package/dist/bundled-skills/email-me/scripts/email_me.js

@@ -0,0 +1,45 @@
+export const description =
+  'Send an email to the signed-in Tarsk user. Use when the user says "email me".';
+
+export const parameters = {
+  type: "object",
+  properties: {
+    subject: { type: "string", description: "Short subject line for the email" },
+    body: {
+      type: "string",
+      description: "Email body: the information the user asked to include",
+    },
+  },
+  required: ["body"],
+};
+
+export async function execute(args, context) {
+  const subject = String(args.subject ?? "").trim() || "Message from Tarsk";
+  const body = String(args.body ?? "").trim();
+  if (!body) {
+    return {
+      content: [{ type: "text", text: "email_me: `body` is empty. Put the information to send in `body`." }],
+    };
+  }
+
+  const result = await context.email.sendToSelf({ subject, body });
+
+  if (result.status === "not-signed-in") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No Tarsk account is signed in. Please log in to Tarsk and ask again.",
+        },
+      ],
+    };
+  }
+
+  if (result.status === "failed") {
+    return {
+      content: [{ type: "text", text: `The email was not sent: ${result.message}` }],
+    };
+  }
+
+  return { content: [{ type: "text", text: `Email sent to ${result.to}.` }] };
+}

package/dist/bundled-skills/handoff/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: handoff
+description: use if user asks for handoff
+argument-hint: "Optional focus for the new chat"
+---
+
+# Handoff
+
+When the user asks for a handoff or invokes this skill, create a new chat in the current project. Do not only write a summary or a temporary handoff file.
+
+Prepare a concise, self-contained first message for the new chat. Include the original ask, decisions and constraints, relevant verified facts, completed work, current state, important paths or links, checks and their outcomes, and unfinished work. Keep details that the next agent needs; do not repeat artifacts that can be referenced by path or URL. Do not include secrets.
+
+If the user provides a focus for the next chat, make it the new chat's primary task. Keep the prior task context that supports that focus, and distinguish facts from assumptions.
+
+List the exact skill references that were used or referenced in this conversation under a "Skills carried forward" section in the first message. Use /name for project or global skills and //name for bundled skills. Do not invent references. The handoff operation copies the current chat's enabled and disabled skill settings and adds a link to the source chat; the listed references preserve explicit skill uses that are not part of those settings.
+
+Choose a short title that describes the focus. Start the new chat by calling context.chat.startHandoff with the title, complete first-message prompt, and skill names. Use context.chat.normalizeTitle to normalize the title. Do not say the new chat started unless the call succeeds.
+
+After success, give the user a markdown link to the new chat using the returned URL. If the launch fails after creating a chat, show the recovery link from the error and state that the first message did not start.

package/dist/bundled-skills/tarsk-agent/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: tarsk-agent
+description: >-
+  How to author, edit, and package Tarsk Tool skills: SKILL.md front matter,
+  scripts/{name}.js contract, Agent runtime (context), and export/resolution.
+  Use when creating or modifying a Tool skill, changing a tool
+  description/schema/execute, or asking what context.* APIs provide.
+version: 2.0.1
+when_to_use: >-
+  Before creating or editing any Skill under .agents/skills or cli/bundled-skills
+  that publishes tools, or when changing tool behavior, parameters, or descriptions.
+  Also when a tool repeatedly fails or a goal burned excessive turns/tokens due to
+  tool design (noisy output, missing select, serial multi-hop).
+---
+
+# Agent runtime & Tool skills (`tarsk-agent`)
+
+Read this before creating or editing a Tool skill. Tool skill scripts must not
+import modules (no `import` / `require`). They receive a `context` object (the
+Agent runtime) as the second argument to `execute`. Project scripts that import
+are rejected at load; use only `context.*`.
+
+## When to update a Tool skill
+
+Edit the project Tool skill (usually `.agents/skills/tarsk-<area>/`) when:
+
+- The same tool call fails repeatedly for a fixable reason (bad defaults, weak
+  validation message, schema that invites wrong args, brittle formatting).
+- Reaching the user's goal took excessive turns or tokens because of tool design
+  (dumping huge results instead of `select` / truncation, forcing grep→read
+  loops that belong in `run_js`, descriptions that send the model down a dead path).
+- A description or parameter shape no longer matches how the tool should be used.
+
+Prefer a small change to `description`, `parameters`, or `execute` over teaching
+the model a one-off workaround in chat. After edit, the next tool load picks it
+up. Do not invent host APIs — use `context.*` below.
+
+## Split of responsibility
+
+| Lives in                | Responsibility                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tool skill scripts**  | Tool logic: description, parameters, orchestration, formatting, policy text the agent may edit                                            |
+| **CLI / Agent runtime** | Security and light host: cwd/path checks, permission gates, seatbelt, fetch allowlist, DB/network clients, truncate helpers, job registry |
+
+Prefer implementing behavior in `scripts/{name}.js` using `context` primitives.
+Heavy engines (edit matching, browser, shell spawn) stay behind dedicated
+`context.*` host APIs — never import Node modules or `cli/src`.
+
+### What you can change
+
+| Goal                                 | How                                                                      |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| Change Tool behavior the agent owns  | Edit `execute` / `description` / `parameters` in the Skill script        |
+| Need filesystem/shell/network safely | Call the matching **secure or light** `context.*` API (documented below) |
+
+## Package layout
+
+A Tool skill is a normal Skill whose front matter lists `tools`:
+
+```text
+.agents/skills/my-notes/          # project copy (edit here)
+  SKILL.md
+  scripts/
+    notes.js                      # one file per name in tools:
+```
+
+Tarsk-shipped defaults live under `cli/bundled-skills/tarsk-*`. To change one, **export**
+it into the Project’s `.agents/skills` (`tarsk-improve`’s `ensure-exported.ts`) and
+**edit the project copy** under `.agents/skills/…` so your changes stick. Chat load
+never creates copies — it only **prunes** project copies that still match bundled — so
+export before editing. The `tarsk-` prefix is a shipping convention for export only;
+any Skill with a `tools` array publishes Tools.
+
+### Front matter
+
+```yaml
+---
+name: my-notes # must match the directory name
+description: Short trigger text for humans and skill discovery
+version: 1.0.0 # semver; used by export
+tools:
+  - notes # model-facing Tool name(s)
+# deferred-tools:              # optional; subset of tools → behind tool_search
+#   - notes
+---
+```
+
+- `tools: [name, …]` — required for a Tool skill. Each name needs `scripts/{name}.js`.
+  Add the name here **before** creating the script: the write guard validates only
+  declared Tool scripts, so a file it does not know is an ordinary helper script
+  (it may import modules; it has no `description`/`parameters`/`execute` contract).
+- `deferred-tools` — optional subset of `tools`; omitted means all eager. Prefer deferring
+  rare tools (browser, jobs, images, web, observations, …) so schemas stay out of every
+  request; keep the coding core eager.
+- A deferred tool is reachable only through `tool_search`, which matches a tool's name and
+  `description` — never its `parameters`. Name every capability a model might search for
+  (for example `screenshot`, `capture`) in the script's `description`, or keyword search
+  cannot find the tool and the model concludes the capability does not exist.
+- Host injects a shared `select` parameter for `read` and `bash` at load time — do not
+  duplicate that schema in the Skill script.
+- Not the same as `allowed-tools` (that only restricts which existing Tools a Skill may use).
+- Directory name must equal front matter `name`.
+
+### Script contract
+
+Each `scripts/{name}.js` (or `.ts`) exports:
+
+- `description` — string shown to the model for this Tool
+- `parameters` — JSON Schema object for arguments
+- `execute(args, context, options?)` — returns
+  `{ content: [{ type: "text", text }], details? }`
+  (throw or return an error text on failure)
+
+The Tool **name** comes from the `tools` array, not from inside the file.
+A script not listed in `tools` is an ordinary skill script (`execute_skill_script`),
+not a model Tool.
+
+`options` (third argument): `{ signal?, onUpdate? }` for abort and streaming
+progress.
+
+## Where files live (export & resolution)
+
+1. **Resolution for a run:** Project `.agents/skills/<name>` if present, else
+   bundled `cli/bundled-skills/<name>`. Load never writes. Script imports are
+   cache-busted by mtime so edits apply on the next tool load. Project scripts
+   must not `import`/`require` modules (rejected at load).
+2. **Export (deliberate):** Run `tarsk-improve`’s `ensure-exported.ts` to copy
+   bundled Skills whose names start with `tarsk-` into `.agents/skills`:
+   - missing project copy → copy
+   - same `version` → leave
+   - bundled **major** > project major → overwrite
+   - otherwise (project ahead, or only minor/patch ahead) → leave project copy
+     Chat load never copies. It only **prunes** a project copy that is byte-identical
+     to bundled, so untouched packages never persist in the repo.
+3. **Where edits land:** in the Tarsk checkout the built-ins under
+   `cli/bundled-skills/tarsk-*` _are_ this repo's own files, so
+   `ensure-exported.ts` copies nothing and `.agents/skills/tarsk-*` stays absent —
+   edit `cli/bundled-skills/tarsk-*` directly. In any other repo do not hand-edit
+   `cli/bundled-skills/`; the project export is the edit surface.
+4. Bump `version` in front matter when you intentionally publish a new Skill
+   revision. A major bump on the bundled side can overwrite local copies.
+
+## Enable / disable
+
+- Tool skills are **enabled by default**.
+- Disabling the Skill (thread skill settings) hides every Tool in its `tools` array.
+- Project `disabledTools` still hides individual Tool names.
+- Disabling `tarsk-agent` does not remove Tools; the CLI always injects `context`.
+
+## `context` API
+
+### Identifiers
+
+| Field            | Meaning                           |
+| ---------------- | --------------------------------- |
+| `cwd`            | Working directory for the run     |
+| `projectId`      | Current Project id (may be empty) |
+| `threadId`       | Current Thread id                 |
+| `conversationId` | Current Conversation id           |
+| `messageId`      | Optional message id               |
+| `threadPath`     | Optional Thread checkout path     |
+
+### `context.notes`
+
+Project-scoped durable notes:
+
+- `list()` — note metadata
+- `read(name, offset?)` — paged content, or `null` if missing
+- `write(name, content)` — replace; empty content clears; metadata or `null` when cleared
+- `append(name, content)` — append a record
+- `search(query)` — name and content excerpts
+
+### `context.chat`
+
+- `titleMaxLength` — max characters for a chat title
+- `normalizeTitle(title)` — normalize a model-supplied title for storage
+
+### `context.mcp`
+
+```js
+await context.mcp.connectRemoteServer(
+  { serverName, url, transport: "streamableHttp" | "sse", useOAuth },
+  options,
+);
+// → { serverName, state, tools, authenticated, error? }
+```
+
+Saves and discovers a remote MCP server for the current project. The active run's tool set stays fixed; discovered MCP tools are available on the next message
+in the same conversation. Use the deferred `connect_mcp` Skill instead of calling
+this host API directly from user-facing replies. Never ask for bearer tokens.
+
+### `context.web`
+
+```js
+await context.web.search({ query, numResults, type, includeDomains, excludeDomains, signal });
+```
+
+### `context.email`
+
+```js
+await context.email.sendToSelf({ subject, body });
+// → { status: "sent", to } | { status: "not-signed-in" } | { status: "failed", message }
+```
+
+Sends an email to the signed-in Tarsk account (the auth service resolves the
+recipient from the sign-in token, so the mail can only reach that user's own
+address). The Skill formats every reply, including the signed-out "log in to
+Tarsk" copy.
+
+### `context.util`
+
+```js
+context.util.maxBytes;
+context.util.formatSize(bytes);
+context.util.truncateHead(text, { maxLines, maxBytes });
+context.util.compressFindPaths(paths); // { text, applied, banner }
+context.util.compressGrepContent(lines); // { text, applied, banner }
+context.util.compressGrepCount(lines);
+context.util.compressGrepFiles(lines);
+context.util.compressUnifiedDiffPreservingFootnotes(text); // { text, applied }
+await context.util.withAbort(signal, async (isAborted) => {
+  /* … */
+});
+```
+
+### `context.history`
+
+```js
+context.history.available
+await context.history.search({ query, allConversations?, limit? })
+await context.history.read({ entryId, allConversations?, offset? })
+```
+
+### `context.jobs`
+
+Owner-scoped background jobs (bash `run_in_background`). Kill is a privileged host op.
+
+```js
+context.jobs.available
+context.jobs.list()
+context.jobs.readOutput(jobId, { offsetLines?, limitLines? })
+context.jobs.kill(jobId) // { ok, outcome, status, exitCode } | { ok: false }
+```
+
+### `context.todos`
+
+Thread-scoped todos and progress.txt append:
+
+```js
+await context.todos.list()
+await context.todos.add(descriptions, assignedTo?)
+await context.todos.update(ids, { status?, assignedTo?, passes? })
+await context.todos.remove(ids)
+await context.todos.appendLearnings(text)
+```
+
+### `context.fs`
+
+Secure filesystem (cwd containment). Grow this as more file Tools migrate.
+
+```js
+await context.fs.writeText(path, content, { signal? })
+// → { path, absolutePath, previousBytes, nextBytes, supersession }
+await context.fs.glob(pattern, { path?, limit?, signal? })
+// → { paths, limit, resultLimitReached }
+await context.fs.applyEdit(args, { signal? }) // structured; Skill formats copy
+await context.fs.read(args, { signal?, onUpdate?, toolCallId? })
+// → structured (text/directory/image/unchanged/raw); Skill formats copy
+await context.fs.grep(args, { signal? })
+// → structured rows; Skill formats banners / empty tips / pagination
+```
+
+### `context.shell` / `context.ask` / `context.web.fetch`
+
+```js
+await context.shell.run(args, options)
+// → structured (completed | background | preformatted); Skill formats notices
+context.shell.resolveExit({
+  exitCode, executionCommand, outputText, fullOutput, threadId?,
+}) // soft-success / soft-fail classification (policy stays in host)
+context.ask.normalize(args); // coerce legacy ask_user shapes
+await context.ask.wait(questions, options); // blocking gate + credentials; needs toolCallId
+await context.web.fetch(args, options); // fetch (allowlist gate)
+```
+
+### `context.observations` (DB only)
+
+```js
+context.observations.limits;
+await context.observations.resolveId(rawId);
+await context.observations.fetch(id); // { id, content, toolName } | null
+await context.observations.recordRetrieved(bytes);
+```
+
+Paging and model copy live in the `get_observation` Skill.
+
+### Other host executors
+
+```js
+await context.images.searchAndSave(args, options); // structured; Skill formats
+await context.images.generate(args, options); // structured; Skill formats
+await context.projects.query(args); // structured; Skill formats
+await context.projects.launch(args); // structured; Skill formats
+await context.tasks.query(args); // structured; Skill formats
+await context.browser.run(args, options); // structured payload; Skill formats
+await context.js.run(args, options); // structured ok / trivial_read; Skill formats
+await context.skillsCatalog.read(args); // structured; Skill formats
+await context.skillsCatalog.executeScript(args, options); // structured; Skill formats
+await context.skillsCatalog.readReference(args); // structured; Skill formats
+```
+
+Every shipped Tool skill uses a dedicated API above (or pure script logic).
+`propose_branch` is Slack plan-chat only.
+
+## Worked example (new Tool skill)
+
+`.agents/skills/echo-tool/SKILL.md`:
+
+```yaml
+---
+name: echo-tool
+description: Echoes a message back via a small custom Tool.
+version: 1.0.0
+tools:
+  - echo_message
+---
+# Echo
+
+Publishes `echo_message`. See `tarsk-agent` for the runtime contract.
+```
+
+`.agents/skills/echo-tool/scripts/echo_message.js`:
+
+```js
+export const description =
+  "Echo a short message back to the conversation. Use for smoke-testing Tool skills.";
+
+export const parameters = {
+  type: "object",
+  properties: {
+    message: { type: "string", description: "Text to echo" },
+  },
+  required: ["message"],
+};
+
+export async function execute(args, context) {
+  const text = String(args.message ?? "");
+  return {
+    content: [{ type: "text", text: `echo (${context.cwd}): ${text}` }],
+    details: undefined,
+  };
+}
+```
+
+### Wrapping a host Tool (change description / formatting)
+
+`.agents/skills/tarsk-bash/scripts/bash.js` (project override after export):
+
+```js
+export const description = "/* your revised guidance for the model */";
+
+export const parameters = {/* keep or tighten the JSON Schema */};
+
+export async function execute(args, context, options) {
+  const structured = await context.shell.run(args, options);
+  // Format completed / background / preformatted + resolveExit — see bundled bash.js
+  // …
+}
+```
+
+After editing a project Tool skill, the next run reload picks it up (no restart
+required beyond the next tool load for that chat).