feat: complete improvement plans 001-013 (cli features, docs expansion, distribution spike)

.tegami/2026-07-01-dev-watch.md

@@ -0,0 +1,10 @@
+---
+packages:
+  "@jalco/ap-sdk": minor
+---
+
+## Add `ap-sdk dev`
+
+Watch mode for plugin authors: `ap-sdk dev` rebuilds on every change to the
+plugin and its referenced files, and `--install` drops the result straight
+into your local harness dirs. Errors keep the watcher alive.

.tegami/2026-07-01-init-command.md

@@ -0,0 +1,10 @@
+---
+packages:
+  "@jalco/ap-sdk": minor
+---
+
+## Add `ap-sdk init`
+
+Scaffold a new plugin project with one command. `ap-sdk init my-plugin` writes
+a working `plugin.ts` (a skill, a command, and instructions) that passes
+`ap-sdk check` as-is, plus a `.gitignore` entry for `.aps-out/`.

.tegami/2026-07-01-npm-source.md

@@ -0,0 +1,12 @@
+---
+packages:
+  "@jalco/ap-sdk": minor
+---
+
+## Install plugins from npm
+
+`ap-sdk install npm:<package>` (and `check`/`build` with the same spec)
+fetches a published package from the npm registry, verifies it's a
+compatible plugin, and installs it — with `npm:<package>@<version>` for
+pinning. Packages can point at a non-root plugin file via an
+`ap-sdk.plugin` field in package.json.

.tegami/2026-07-01-package-readme.md

@@ -0,0 +1,10 @@
+---
+packages:
+  "@jalco/ap-sdk": patch
+---
+
+### Add a package README
+
+The npm page for `@jalco/ap-sdk` now has a readme covering the full feature
+surface (skills, commands, subagents, hooks, MCP, shared tools) and the
+`ap-sdk port` migration path.

.tegami/2026-07-01-uninstall.md

@@ -0,0 +1,11 @@
+---
+packages:
+  "@jalco/ap-sdk": minor
+---
+
+## Add `ap-sdk uninstall`
+
+`install` now records what it wrote to an install manifest
+(`.ap-sdk/install-manifest.json`), and `ap-sdk uninstall <plugin-id>` cleanly
+reverses it — deleting the plugin's files and removing only its entries from
+merged configs (instruction blocks, MCP servers, hooks).

README.md

@@ -39,13 +39,40 @@ ap-sdk build      # → .aps-out/{claude,codex,gemini,copilot,cursor,windsurf,pi
 ap-sdk install    # → drops artifacts into your local harness dirs
 ```
 
+## What you can define
+
+| Field | What it becomes |
+| --- | --- |
+| [`instructions`](https://ap-sdk.dev/docs) | Always-on system or project guidance for every supported harness. |
+| [`skills`](https://ap-sdk.dev/docs) | Reusable skill documents with descriptions and instructions. |
+| [`commands`](https://ap-sdk.dev/docs) | Slash commands or prompt commands in harnesses that support them. |
+| [`subagents`](https://ap-sdk.dev/docs) | Named specialist agents with their own prompts, tools, and model hints. |
+| [`hooks`](https://ap-sdk.dev/docs) | Lifecycle hooks and scripts translated to each harness' event model. |
+| [`mcpServers`](https://ap-sdk.dev/docs) | MCP server config emitted in native JSON/TOML/YAML formats. |
+| [`tools`](https://ap-sdk.dev/docs) | Shared TypeScript tool implementations with per-harness glue. |
+| [`files`](https://ap-sdk.dev/docs) | Companion files copied next to the generated native artifacts. |
+
+See the [support matrix](https://ap-sdk.dev/docs/harnesses) for what each harness supports.
+
+## Already have a plugin?
+
+Point `ap-sdk port` at an existing Claude Code, Cursor, Codex, Gemini, Copilot, Windsurf, Pi, or OpenCode layout and it generates a portable `plugin.ts` that loads your existing files instead of inlining them.
+
+```bash
+npx ap-sdk port ./my-plugin
+npx ap-sdk check ./plugin.ts
+npx ap-sdk install owner/repo
+```
+
+Read the [porting guide](https://ap-sdk.dev/docs/porting), or install straight from GitHub with `ap-sdk install owner/repo`.
+
 ## Install
 
 ```bash
 pnpm add -D @jalco/ap-sdk
 ```
 
-[Docs](https://github.com/jal-co/agent-plugin-sdk) · [Examples](./packages/agent-plugin-sdk/examples)
+[Docs](https://ap-sdk.dev/docs) · [Examples](https://github.com/jal-co/agent-plugin-sdk/tree/main/packages/agent-plugin-sdk/examples)
 
 ## License
 

apps/docs/content/docs/api/harness.mdx

@@ -0,0 +1,44 @@
+---
+title: Harness entrypoint
+description: Harness authoring toolkit for custom targets.
+---
+
+## defineHarness
+
+Identity helper for a custom target harness: support map, emit translator, install paths, and native config behavior.
+
+```ts
+export function defineHarness(harness: Harness): Harness;
+```
+
+## registerHarness
+
+Registers a custom harness id so build, install, and CLI target validation can use it.
+
+```ts
+export function registerHarness(harness: Harness): void;
+```
+
+## Harness
+
+The contract every built-in and custom harness implements: id, display name, support map, emit function, and install path helpers.
+
+```ts
+export interface Harness { id: HarnessId; displayName: string; supports: FeatureSupport; ... }
+```
+
+## EmitContext
+
+Context passed to emitters, including helper methods and target metadata.
+
+```ts
+export interface EmitContext { harness: Harness; ... }
+```
+
+## InstallScope
+
+Where install writes artifacts: project directories or home-directory global config.
+
+```ts
+export type InstallScope = 'project' | 'global';
+```

apps/docs/content/docs/api/index.mdx

@@ -0,0 +1,13 @@
+---
+title: API reference
+description: Generated reference for the public ap-sdk entrypoints.
+---
+
+This section is generated from source-aligned API metadata. Regenerate it with `pnpm --filter @jal-co/docs generate:api`.
+
+<Cards>
+  <Card title="@jalco/ap-sdk" href="/docs/api/main" />
+  <Card title="@jalco/ap-sdk/runtime" href="/docs/api/runtime" />
+  <Card title="@jalco/ap-sdk/harness" href="/docs/api/harness" />
+  <Card title="Feature guides" href="/docs/skills" />
+</Cards>

apps/docs/content/docs/api/main.mdx

@@ -0,0 +1,84 @@
+---
+title: Main entrypoint
+description: Public helpers and types exported by @jalco/ap-sdk.
+---
+
+## definePlugin
+
+Identity helper for a portable plugin definition. Author once, then build or install native artifacts for each harness.
+
+```ts
+export function definePlugin(plugin: Plugin): Plugin;
+```
+
+## defineSkill
+
+Defines a portable agent skill with a trigger description, instructions, optional resources, and harness metadata.
+
+```ts
+export function defineSkill(skill: Skill): Skill;
+```
+
+## defineCommand
+
+Defines a portable slash command or prompt command with argument templating and per-harness overrides.
+
+```ts
+export function defineCommand(command: Command): Command;
+```
+
+## defineSubagent
+
+Defines a specialist agent prompt with optional tools and target-specific model settings.
+
+```ts
+export function defineSubagent(subagent: Subagent): Subagent;
+```
+
+## defineHook
+
+Defines a lifecycle hook using ap-sdk's portable event names and optional native overrides.
+
+```ts
+export function defineHook(hook: Hook): Hook;
+```
+
+## Plugin
+
+The root declaration: id, description, instructions, skills, commands, MCP servers, subagents, hooks, files, tools, and marketplace metadata.
+
+```ts
+export interface Plugin { id: string; description: string; ... }
+```
+
+## Skill
+
+Reusable instructions plus metadata. Descriptions are capped to the tightest harness limit and drive skill routing.
+
+```ts
+export interface Skill { name: string; description: string; instructions: string; ... }
+```
+
+## Hook
+
+Portable hook event, matcher, command, timeout, async flag, and per-harness event or matcher overrides.
+
+```ts
+export interface Hook { event: HookEvent; command: string | HookCommand; ... }
+```
+
+## build
+
+Validates a plugin and returns in-memory output files and warnings for each requested harness.
+
+```ts
+export function build(plugin: Plugin, options?: BuildOptions): HarnessBuild[];
+```
+
+## installSkills
+
+Installs emitted skills, commands, MCP config, hooks, instructions, subagents, and files into live harness directories.
+
+```ts
+export function installSkills(plugin: Plugin, options?: InstallOptions): InstalledItem[];
+```

apps/docs/content/docs/api/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "API",
+  "pages": ["index", "main", "runtime", "harness"]
+}

apps/docs/content/docs/api/runtime.mdx

@@ -0,0 +1,36 @@
+---
+title: Runtime entrypoint
+description: Runtime helpers for portable tools.
+---
+
+## defineTool
+
+Defines one executable tool with metadata, JSON schema parameters, and a single handler shared across harness adapters.
+
+```ts
+export function defineTool<Args>(tool: Tool<Args>): Tool<Args>;
+```
+
+## listTools
+
+Loads a tools module and returns the declared tool metadata for local inspection or generated adapters.
+
+```ts
+export async function listTools(modulePath: string): Promise<Tool[]>;
+```
+
+## callTool
+
+Invokes a named tool locally with JSON arguments, matching the CLI's `ap-sdk tools --call` loop.
+
+```ts
+export async function callTool(modulePath: string, name: string, args: unknown): Promise<ToolResult>;
+```
+
+## contentToText
+
+Converts structured tool content blocks into plain text for terminal output.
+
+```ts
+export function contentToText(content: ToolContent[]): string;
+```

apps/docs/content/docs/commands.mdx

@@ -0,0 +1,45 @@
+---
+title: Commands
+description: Define portable slash commands and prompt commands with argument templates.
+---
+
+Commands compile to each harness' native command or prompt file. Use them for repeatable workflows where the user explicitly invokes an action.
+
+```ts title="plugin.ts"
+import { defineCommand, definePlugin } from "@jalco/ap-sdk";
+
+export default definePlugin({
+  id: "issue-tools",
+  description: "Issue triage commands.",
+  commands: [
+    defineCommand({
+      name: "fix-issue",
+      description: "Fix a GitHub issue end to end.",
+      argumentHint: "<issue-number>",
+      allowedTools: ["Bash", "Read", "Edit"],
+      body: "Fix issue #$1. Use $ARGUMENTS as the raw user request.",
+      harness: { claude: { model: "sonnet" }, opencode: { model: "gpt-5" } },
+    }),
+  ],
+});
+```
+
+## Argument templates
+
+| Template | Meaning | Portability |
+| --- | --- | --- |
+| `$ARGUMENTS` | The complete argument string. | Portable everywhere. |
+| `$1`, `$2` | 1-based positional args in ap-sdk source. | Claude is rewritten to its 0-based native form. |
+| `` !`shell` `` | Native shell interpolation. | Passed through for Claude and OpenCode. |
+| `@file` | Native file reference. | Passed through for Claude and OpenCode. |
+
+## Fields
+
+- `name`, `description`, `argumentHint`, and `body` define the command.
+- `allowedTools` is honored by Claude Code.
+- `frontmatter` is honored by YAML-frontmatter harnesses; Gemini TOML and Cursor plain markdown ignore it.
+- `harness.claude.model`, `harness.opencode.model`, and `harness.copilot.model` / `agent` set native model hints.
+
+## Portability notes
+
+If a harness cannot represent command metadata, the command body still emits and the build reports a warning for the unsupported option. Next: [subagents](/docs/subagents) and the [support matrix](/docs/harnesses).

apps/docs/content/docs/hooks.mdx

@@ -0,0 +1,53 @@
+---
+title: Hooks
+description: Translate lifecycle hooks and scripts across harness event models.
+---
+
+Hooks run commands around tool calls, prompts, sessions, and agent stops. ap-sdk uses a portable event vocabulary and translates native event spellings where a harness supports hooks.
+
+```ts title="plugin.ts"
+import { defineHook, definePlugin } from "@jalco/ap-sdk";
+
+export default definePlugin({
+  id: "plan-review",
+  description: "Review plans before execution.",
+  hooks: [
+    defineHook({
+      event: "pre-tool-use",
+      matcher: "ExitPlanMode",
+      command: { unix: "node hooks/plan-review.mjs", powershell: "node hooks/plan-review.mjs" },
+      timeout: 120,
+      async: true,
+      harness: { codex: { event: "stop", matcher: undefined } },
+    }),
+  ],
+});
+```
+
+## Portable events
+
+| ap-sdk event | Claude | Copilot | Gemini |
+| --- | --- | --- | --- |
+| `pre-tool-use` | `PreToolUse` | `preToolUse` | `BeforeTool` |
+| `post-tool-use` | `PostToolUse` | `postToolUse` | `AfterTool` |
+| `stop` | `Stop` | `stop` | `Stop` |
+| `user-prompt-submit` | `UserPromptSubmit` | `userPromptSubmit` | `UserPromptSubmit` |
+| `session-start` | `SessionStart` | `sessionStart` | `SessionStart` |
+| `notification` | `Notification` | `notification` | `Notification` |
+| `permission-request` | `PermissionRequest` | `permissionRequest` | `PermissionRequest` |
+| `subagent-stop` | `SubagentStop` | `subagentStop` | `SubagentStop` |
+| `pre-compact` | `PreCompact` | `preCompact` | `PreCompact` |
+| `session-end` | `SessionEnd` | `sessionEnd` | `SessionEnd` |
+
+## Fields
+
+- `event`, `matcher`, `command`, and `timeout` define the hook.
+- `async` is native in Claude and dropped with a warning elsewhere.
+- Object commands can provide `unix` and `powershell`; PowerShell is used by Copilot.
+- `harness.<target>.event` and `matcher` override native mapping. Use `matcher: undefined` to explicitly clear a matcher.
+
+<Callout variant="note" title="Code-only harnesses">
+Pi and OpenCode hooks are code-only today; builds note the limitation instead of emitting a misleading artifact.
+</Callout>
+
+Next: [MCP servers](/docs/mcp) and the [support matrix](/docs/harnesses).