@agent-workshop/adoc-plugin-kit 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2026 adoc contributors
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,49 @@
+# Third-party notices
+
+adoc's original code and documentation use the Zero-Clause BSD License (0BSD). That license does not replace the
+licenses of third-party components, and no third-party component is relicensed by this repository.
+
+## Browser distributions
+
+Two packages carry bundled browser code:
+
+- `@agent-workshop/adoc-webapp`: the web UI in `dist/`. Its build records the packages actually bundled in
+  `dist/licenses/packages.json` and copies their upstream LICENSE, COPYING, COPYRIGHT and NOTICE files beneath
+  `dist/licenses/`.
+- `@agent-workshop/adoc-plugin-sketch`: the drawing board in `client/`, with its inventory and license files in
+  `client/licenses/`.
+
+Keep these files when redistributing the built browser assets.
+
+The main browser dependencies are React, React DOM, React Router, Mermaid (with KaTeX), xterm.js and Lucide in the web
+UI, and Excalidraw with React and Radix UI in the drawing board. Most use MIT, ISC, BSD or Apache-2.0.
+
+- DOMPurify offers MPL-2.0 OR Apache-2.0; adoc uses the Apache-2.0 option.
+- Some packages are published without a license file although their manifest names one: Excalidraw, the Radix UI
+  primitives, react-remove-scroll-bar and fastdom (all MIT). The build includes the upstream texts kept in
+  `tooling/licenses/`.
+
+### Eclipse Layout Kernel / elkjs
+
+Mermaid bundles elkjs, a separately licensed layout engine, which adoc uses under EPL-2.0 without modifying it. Its
+license is included in the generated license inventory. Corresponding source is available from:
+
+- https://github.com/kieler/elkjs (select the release matching the inventory version)
+- https://github.com/eclipse/elk (the underlying Eclipse Layout Kernel)
+- https://www.eclipse.org/legal/epl-2.0/
+
+Recipients may obtain, modify and redistribute the EPL-covered source under EPL-2.0. adoc's 0BSD license applies to its
+independent code, not to ELK.
+
+## Fonts
+
+- The web UI serves Pretendard, D2Coding (both SIL Open Font License 1.1) and Symbols Nerd Font Mono; their license
+  files are next to them in `dist/assets/fonts/`.
+- The drawing board serves the fonts that Excalidraw ships in `client/fonts/` (Excalifont, Virgil, Nunito, Lilita One,
+  Comic Shanns, Cascadia Code, Liberation Sans, Assistant and Xiaolai); they are distributed under the terms that
+  Excalidraw states for them in https://github.com/excalidraw/excalidraw.
+
+## Installed runtime dependencies
+
+The packages that npm installs next to adoc, such as the MCP SDK, ws, yaml, zod, semver, commander, markdown-it and
+highlight.js, are not bundled: each keeps its own license in its own package.

package/dist/define.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { PluginDefinition } from './types.js';
+import { HtmlFragment } from './types.js';
+/** Validates what `summarize` returned. */
+export declare const summarySchema: z.ZodObject<{
+    title: z.ZodString;
+    status: z.ZodString;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+/** Validates what an action handler returned. */
+export declare const actionResultSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        base64: z.ZodString;
+    }, z.core.$strict>]>>>;
+    companions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        base64: z.ZodString;
+    }, z.core.$strict>]>>>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Validates what `render` returned. */
+export declare const renderResultSchema: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<HtmlFragment, HtmlFragment>]>;
+/** Turns a zod error into one line per problem: `field.path: message`. */
+export declare function describeIssues(error: z.ZodError, prefix: string): string;
+/**
+ * Declares a plugin. Default-export its result from the plugin's `index.ts`.
+ * Throws a one-line error naming each wrong field, so mistakes show up when adoc loads the plugin.
+ */
+export declare function definePlugin(definition: PluginDefinition): PluginDefinition;

package/dist/define.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { HtmlFragment } from './types.js';
+const fn = z.custom((v) => typeof v === 'function', 'must be a function');
+const EXTENSION = /^\.[a-z0-9]+$/;
+const layoutSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('file'),
+        extension: z.string().regex(EXTENSION, 'must look like ".md" (a dot, then lowercase letters or digits)'),
+        companions: z.array(z.string().regex(EXTENSION, 'each must look like ".png" (a dot, then lowercase letters or digits)')).optional(),
+    }),
+    z.object({ kind: z.literal('folder'), entry: z.string().regex(/^[^/\\]+$/, 'must be a file name inside the folder, such as "bug.yaml"') }),
+]);
+/** Action names the web UI's document header sends for every document; the agent handles them, never a plugin. */
+const RESERVED_ACTIONS = ['archive', 'unarchive'];
+const definitionSchema = z.object({
+    description: z.string().min(1, 'must be a non-empty one-line description'),
+    layout: layoutSchema,
+    summarize: fn,
+    render: fn,
+    renderChanges: fn.optional(),
+    actions: z
+        .record(z.string().regex(/^[a-z][a-z0-9-]*$/, 'action names must be lowercase words such as "toggle"'), fn)
+        .superRefine((actions, context) => {
+        for (const name of RESERVED_ACTIONS.filter((reserved) => reserved in actions)) {
+            context.addIssue({ code: 'custom', path: [name], message: 'archive and unarchive are sent by the document header for the agent; choose another name' });
+        }
+    })
+        .optional(),
+});
+/** Validates what `summarize` returned. */
+export const summarySchema = z.object({
+    title: z.string(),
+    status: z.string(),
+    fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+});
+/** A file content in an action result: text, or binary data as base64. */
+const contentSchema = z.union([z.string(), z.object({ base64: z.string() }).strict()]);
+/** Validates what an action handler returned. */
+export const actionResultSchema = z
+    .object({
+    text: z.string().optional(),
+    files: z.record(z.string(), contentSchema).optional(),
+    companions: z.record(z.string(), contentSchema).optional(),
+    message: z.string().optional(),
+})
+    .strict();
+/** Validates what `render` returned. */
+export const renderResultSchema = z.union([z.string(), z.instanceof(HtmlFragment)], {
+    error: 'must return a string or the result of html`…`',
+});
+/** Turns a zod error into one line per problem: `field.path: message`. */
+export function describeIssues(error, prefix) {
+    return error.issues.map((issue) => `${[prefix, ...issue.path.map(String)].filter(Boolean).join('.')}: ${issue.message}`).join('; ');
+}
+/**
+ * Declares a plugin. Default-export its result from the plugin's `index.ts`.
+ * Throws a one-line error naming each wrong field, so mistakes show up when adoc loads the plugin.
+ */
+export function definePlugin(definition) {
+    const result = definitionSchema.safeParse(definition);
+    if (!result.success)
+        throw new Error(`definePlugin: ${describeIssues(result.error, '')}`);
+    return definition;
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}

package/dist/diff.d.ts

@@ -0,0 +1,21 @@
+import type { HtmlFragment } from './types.js';
+/** One line of a line diff. `line` is the 1-based line in the new text for `same` and `added`, in the old text for `removed`. */
+export interface DiffLine {
+    op: 'same' | 'added' | 'removed';
+    text: string;
+    line: number;
+}
+/** Compares two texts line by line (longest common subsequence). */
+export declare function diffLines(oldText: string, newText: string): DiffLine[];
+/**
+ * Renders a line diff of two texts as HTML: added lines get `adoc-added`, removed lines `adoc-removed`.
+ * With `file`, current lines carry their source position so that comments in the diff still point at the file.
+ */
+export declare function sourceDiff(oldText: string, newText: string, options?: {
+    file?: string;
+}): HtmlFragment;
+/**
+ * Writes the changes from one text to another as a unified diff (`--- a/<file>`, `+++ b/<file>`, `@@` hunks with
+ * `context` unchanged lines around each change). Empty when the texts are equal.
+ */
+export declare function unifiedDiff(oldText: string, newText: string, file: string, context?: number): string;

package/dist/diff.js

@@ -0,0 +1,87 @@
+import { escapeHtml, raw } from './html.js';
+const LIMIT = 4_000_000;
+/** Compares two texts line by line (longest common subsequence). */
+export function diffLines(oldText, newText) {
+    const a = oldText.split('\n');
+    const b = newText.split('\n');
+    if (a.length * b.length > LIMIT) {
+        return [...a.map((text, i) => ({ op: 'removed', text, line: i + 1 })), ...b.map((text, i) => ({ op: 'added', text, line: i + 1 }))];
+    }
+    const lcs = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--)
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j])
+            out.push({ op: 'same', text: b[j], line: ++j }), i++;
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            out.push({ op: 'removed', text: a[i], line: ++i });
+        else
+            out.push({ op: 'added', text: b[j], line: ++j });
+    }
+    while (i < a.length)
+        out.push({ op: 'removed', text: a[i], line: ++i });
+    while (j < b.length)
+        out.push({ op: 'added', text: b[j], line: ++j });
+    return out;
+}
+/**
+ * Renders a line diff of two texts as HTML: added lines get `adoc-added`, removed lines `adoc-removed`.
+ * With `file`, current lines carry their source position so that comments in the diff still point at the file.
+ */
+export function sourceDiff(oldText, newText, options = {}) {
+    const rows = diffLines(oldText, newText).map((d) => {
+        const cls = d.op === 'same' ? 'adoc-same' : d.op === 'added' ? 'adoc-added' : 'adoc-removed';
+        const mark = d.op === 'same' ? ' ' : d.op === 'added' ? '+' : '-';
+        const src = options.file && d.op !== 'removed' ? ` data-adoc-source="${escapeHtml(`${options.file}:${d.line}`)}"` : '';
+        return `<div class="${cls}"${src}><span class="adoc-diff-mark">${mark}</span>${escapeHtml(d.text) || ' '}</div>`;
+    });
+    return raw(`<div class="adoc-diff">${rows.join('')}</div>`);
+}
+/**
+ * Writes the changes from one text to another as a unified diff (`--- a/<file>`, `+++ b/<file>`, `@@` hunks with
+ * `context` unchanged lines around each change). Empty when the texts are equal.
+ */
+export function unifiedDiff(oldText, newText, file, context = 2) {
+    const lines = diffLines(oldText, newText);
+    const numbered = [];
+    let oldLine = 0;
+    let newLine = 0;
+    for (const line of lines) {
+        if (line.op !== 'added')
+            oldLine++;
+        if (line.op !== 'removed')
+            newLine++;
+        numbered.push({ op: line.op, text: line.text, oldLine, newLine });
+    }
+    const changed = numbered.map((l, i) => (l.op === 'same' ? -1 : i)).filter((i) => i >= 0);
+    if (!changed.length)
+        return '';
+    const hunks = [];
+    for (const i of changed) {
+        const from = Math.max(0, i - context);
+        const to = Math.min(numbered.length - 1, i + context);
+        const last = hunks.at(-1);
+        if (last && from <= last[1] + 1)
+            last[1] = Math.max(last[1], to);
+        else
+            hunks.push([from, to]);
+    }
+    const out = [`--- a/${file}`, `+++ b/${file}`];
+    for (const [from, to] of hunks) {
+        const part = numbered.slice(from, to + 1);
+        const oldCount = part.filter((l) => l.op !== 'added').length;
+        const newCount = part.filter((l) => l.op !== 'removed').length;
+        const oldStart = part.find((l) => l.op !== 'added')?.oldLine ?? numbered[from].oldLine;
+        const newStart = part.find((l) => l.op !== 'removed')?.newLine ?? numbered[from].newLine;
+        out.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+        for (const l of part)
+            out.push(`${l.op === 'added' ? '+' : l.op === 'removed' ? '-' : ' '}${l.text}`);
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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"}

package/dist/html.d.ts

@@ -0,0 +1,12 @@
+import { HtmlFragment } from './types.js';
+/** Escapes text for HTML content and attribute values. */
+export declare function escapeHtml(value: string): string;
+/** Marks a string as trusted HTML so that `html` inserts it unescaped. */
+export declare function raw(value: string): HtmlFragment;
+/**
+ * Builds HTML. Interpolated values are escaped, except `HtmlFragment`s from `html`, `raw`,
+ * `markdown` and the markup helpers. Arrays are joined; `null`, `undefined` and `false` print nothing.
+ *
+ *     html`<li ${anchor(item.id)}>${item.text}</li>`
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlFragment;

package/dist/html.js

@@ -0,0 +1,33 @@
+import { HtmlFragment } from './types.js';
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+/** Escapes text for HTML content and attribute values. */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (c) => ESCAPES[c]);
+}
+/** Marks a string as trusted HTML so that `html` inserts it unescaped. */
+export function raw(value) {
+    return new HtmlFragment(value);
+}
+function interpolate(value) {
+    if (value instanceof HtmlFragment)
+        return value.html;
+    if (Array.isArray(value))
+        return value.map(interpolate).join('');
+    if (value === null || value === undefined || value === false)
+        return '';
+    return escapeHtml(String(value));
+}
+/**
+ * Builds HTML. Interpolated values are escaped, except `HtmlFragment`s from `html`, `raw`,
+ * `markdown` and the markup helpers. Arrays are joined; `null`, `undefined` and `false` print nothing.
+ *
+ *     html`<li ${anchor(item.id)}>${item.text}</li>`
+ */
+export function html(strings, ...values) {
+    let out = strings[0];
+    values.forEach((value, index) => {
+        out += interpolate(value) + strings[index + 1];
+    });
+    return new HtmlFragment(out);
+}
+//# sourceMappingURL=html.js.map

package/dist/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,OAAO,GAA2B,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAEhH,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;AACvD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,GAAG,CAAC,KAAa;IAC/B,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IACxE,OAAO,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,OAA6B,EAAE,GAAG,MAAiB;IACtE,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;IACtB,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,GAAG,CAAC,CAAE,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { ActionEvent, ActionHandler, ActionResult, DocumentLayout, DocumentSummary, FileContent, PluginDefinition, PluginDocument, } from './types.js';
+export { HtmlFragment } from './types.js';
+export { definePlugin, summarySchema, actionResultSchema, renderResultSchema, describeIssues } from './define.js';
+export { html, raw, escapeHtml } from './html.js';
+export { anchor, source, action, dropTarget, ref, slug } from './markup.js';
+export { diffLines, sourceDiff, unifiedDiff } from './diff.js';
+export type { DiffLine } from './diff.js';
+export { markdown, frontmatter, findReferences, REFERENCE_PATTERN } from './markdown.js';
+export type { MarkdownOptions } from './markdown.js';
+export { parse as parseYaml, stringify as stringifyYaml } from 'yaml';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { HtmlFragment } from './types.js';
+export { definePlugin, summarySchema, actionResultSchema, renderResultSchema, describeIssues } from './define.js';
+export { html, raw, escapeHtml } from './html.js';
+export { anchor, source, action, dropTarget, ref, slug } from './markup.js';
+export { diffLines, sourceDiff, unifiedDiff } from './diff.js';
+export { markdown, frontmatter, findReferences, REFERENCE_PATTERN } from './markdown.js';
+export { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC"}

package/dist/markdown.d.ts

@@ -0,0 +1,32 @@
+import type { HtmlFragment } from './types.js';
+/** The reference notation `[[KEY]]` or `[[KEY#anchor]]`. */
+export declare const REFERENCE_PATTERN: RegExp;
+export interface MarkdownOptions {
+    /** The workspace-relative file the text comes from, usually `doc.file`. Enables source positions. */
+    file?: string;
+    /** The 1-based line in `file` where `text` starts. Default 1. */
+    line?: number;
+    /** Render a single line without a surrounding paragraph. */
+    inline?: boolean;
+}
+/**
+ * Renders Markdown to trusted HTML.
+ * - `[[KEY]]` and `[[KEY#anchor]]` become reference links.
+ * - With `file`, every block element gets its source position, so comments carry `file:line`.
+ * - A list item starting with `[ ] ` or `[x] ` gets a read-only checkbox.
+ * - A fenced block of a known language is syntax-highlighted; a ```mermaid block is drawn as a diagram by the web UI.
+ * - Raw HTML in the text is escaped.
+ */
+export declare function markdown(text: string, options?: MarkdownOptions): HtmlFragment;
+/** Lists every reference key written as `[[KEY]]` in the text. */
+export declare function findReferences(text: string): string[];
+/**
+ * Splits YAML front matter from Markdown.
+ * Returns the parsed data, the body and `bodyLine`, the 1-based line where the body starts,
+ * which is what `markdown(body, { file, line: bodyLine })` needs.
+ */
+export declare function frontmatter(text: string): {
+    data: Record<string, unknown>;
+    body: string;
+    bodyLine: number;
+};

package/dist/markdown.js

@@ -0,0 +1,100 @@
+import hljs from 'highlight.js/lib/common';
+import markdownIt from 'markdown-it';
+import { parse as parseYaml } from 'yaml';
+import { raw } from './html.js';
+import { ref } from './markup.js';
+/** The reference notation `[[KEY]]` or `[[KEY#anchor]]`. */
+export const REFERENCE_PATTERN = /\[\[([A-Z]+-[a-z0-9._-]+(?:#[^\]\s]+)?)\]\]/g;
+function referenceRule(state, silent) {
+    const src = state.src;
+    if (src.charCodeAt(state.pos) !== 0x5b || src.charCodeAt(state.pos + 1) !== 0x5b)
+        return false;
+    const match = /^\[\[([A-Z]+-[a-z0-9._-]+(?:#[^\]\s]+)?)\]\]/.exec(src.slice(state.pos));
+    if (!match)
+        return false;
+    if (!silent) {
+        const token = state.push('adoc_ref', '', 0);
+        token.content = match[1];
+    }
+    state.pos += match[0].length;
+    return true;
+}
+/** A list item starting with `[ ] ` or `[x] ` shows a read-only checkbox, as in GitHub's task lists. */
+function taskListRule(state) {
+    const tokens = state.tokens;
+    for (let i = 2; i < tokens.length; i++) {
+        const inline = tokens[i];
+        if (inline.type !== 'inline' || tokens[i - 1].type !== 'paragraph_open' || tokens[i - 2].type !== 'list_item_open')
+            continue;
+        const first = inline.children?.[0];
+        const match = first?.type === 'text' ? /^\[([ xX])\] /.exec(first.content) : null;
+        if (!first || !match)
+            continue;
+        first.content = first.content.slice(match[0].length);
+        const box = new state.Token('html_inline', '', 0);
+        box.content = `<input type="checkbox" disabled${match[1] === ' ' ? '' : ' checked'}> `;
+        inline.children.unshift(box);
+        tokens[i - 2].attrJoin('class', 'adoc-task-item');
+    }
+}
+function createParser() {
+    // A fence that names a known language gets highlight.js `hljs-*` classes, which the web UI theme colours.
+    const highlight = (code, language) => (language && hljs.getLanguage(language) ? hljs.highlight(code, { language, ignoreIllegals: true }).value : '');
+    const md = markdownIt({ html: false, linkify: true, highlight });
+    md.inline.ruler.before('link', 'adoc_ref', referenceRule);
+    md.core.ruler.after('inline', 'adoc_task_list', taskListRule);
+    md.renderer.rules.adoc_ref = (tokens, idx) => ref(tokens[idx].content).html;
+    // A ```mermaid fence stays its escaped source, marked for the web UI, which draws it as a diagram.
+    const fence = md.renderer.rules.fence;
+    md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+        const token = tokens[idx];
+        if (token.info.trim() !== 'mermaid')
+            return fence(tokens, idx, options, env, self);
+        token.attrJoin('class', 'adoc-mermaid');
+        return `<pre${self.renderAttrs(token)}>${md.utils.escapeHtml(token.content)}</pre>\n`;
+    };
+    return md;
+}
+const parser = createParser();
+/**
+ * Renders Markdown to trusted HTML.
+ * - `[[KEY]]` and `[[KEY#anchor]]` become reference links.
+ * - With `file`, every block element gets its source position, so comments carry `file:line`.
+ * - A list item starting with `[ ] ` or `[x] ` gets a read-only checkbox.
+ * - A fenced block of a known language is syntax-highlighted; a ```mermaid block is drawn as a diagram by the web UI.
+ * - Raw HTML in the text is escaped.
+ */
+export function markdown(text, options = {}) {
+    if (options.inline)
+        return raw(parser.renderInline(text));
+    const tokens = parser.parse(text, {});
+    if (options.file !== undefined) {
+        const first = options.line ?? 1;
+        for (const token of tokens) {
+            if (token.map && (token.nesting === 1 || token.type === 'fence' || token.type === 'code_block' || token.type === 'hr')) {
+                token.attrSet('data-adoc-source', `${options.file}:${first + token.map[0]}`);
+            }
+        }
+    }
+    return raw(parser.renderer.render(tokens, parser.options, {}));
+}
+/** Lists every reference key written as `[[KEY]]` in the text. */
+export function findReferences(text) {
+    return [...text.matchAll(REFERENCE_PATTERN)].map((m) => m[1]);
+}
+/**
+ * Splits YAML front matter from Markdown.
+ * Returns the parsed data, the body and `bodyLine`, the 1-based line where the body starts,
+ * which is what `markdown(body, { file, line: bodyLine })` needs.
+ */
+export function frontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!match)
+        return { data: {}, body: text, bodyLine: 1 };
+    const data = (parseYaml(match[1]) ?? {});
+    if (typeof data !== 'object' || Array.isArray(data))
+        throw new Error('front matter must be a YAML mapping');
+    const bodyLine = match[0].split('\n').length - (match[0].endsWith('\n') ? 0 : 1);
+    return { data, body: text.slice(match[0].length), bodyLine };
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"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"}

package/dist/markup.d.ts

@@ -0,0 +1,23 @@
+import type { HtmlFragment } from './types.js';
+/** Attributes that make an element a document anchor. Put them inside a start tag: html`<li ${anchor('123')}>`. */
+export declare function anchor(value: string | number): HtmlFragment;
+/** Attributes that record the source position of an element, such as `TASK-a.md:12`. */
+export declare function source(file: string, line: number): HtmlFragment;
+/**
+ * Attributes that make an element an action control.
+ * - `click`: put on a `<button>`.
+ * - `toggle`: put on an `<input type="checkbox">`; the handler receives `checked`.
+ * - `drag`: put on the dragged element; pair it with `dropTarget(name, value)` on each drop zone.
+ */
+export declare function action(spec: {
+    kind: 'click' | 'toggle' | 'drag';
+    name: string;
+    value?: string | number;
+    confirm?: string;
+}): HtmlFragment;
+/** Attributes that make an element a drop zone for the drag action `name`; the handler receives `value` as `to`. */
+export declare function dropTarget(name: string, value: string | number): HtmlFragment;
+/** A complete reference link to another document, such as `TASK-1231` or `TASK-1231#method`. */
+export declare function ref(target: string, label?: string): HtmlFragment;
+/** Turns heading text into an anchor value: `Completion Criteria` becomes `completion-criteria`. */
+export declare function slug(text: string): string;

package/dist/markup.js

@@ -0,0 +1,42 @@
+import { escapeHtml, raw } from './html.js';
+function attr(name, value) {
+    return `${name}="${escapeHtml(value)}"`;
+}
+/** Attributes that make an element a document anchor. Put them inside a start tag: html`<li ${anchor('123')}>`. */
+export function anchor(value) {
+    return raw(attr('data-adoc-anchor', String(value)));
+}
+/** Attributes that record the source position of an element, such as `TASK-a.md:12`. */
+export function source(file, line) {
+    return raw(attr('data-adoc-source', `${file}:${line}`));
+}
+/**
+ * Attributes that make an element an action control.
+ * - `click`: put on a `<button>`.
+ * - `toggle`: put on an `<input type="checkbox">`; the handler receives `checked`.
+ * - `drag`: put on the dragged element; pair it with `dropTarget(name, value)` on each drop zone.
+ */
+export function action(spec) {
+    const parts = [attr('data-adoc-action', spec.name), attr('data-adoc-kind', spec.kind), attr('data-adoc-value', String(spec.value ?? ''))];
+    if (spec.confirm)
+        parts.push(attr('data-adoc-confirm', spec.confirm));
+    if (spec.kind === 'drag')
+        parts.push('draggable="true"');
+    return raw(parts.join(' '));
+}
+/** Attributes that make an element a drop zone for the drag action `name`; the handler receives `value` as `to`. */
+export function dropTarget(name, value) {
+    return raw(`${attr('data-adoc-drop', name)} ${attr('data-adoc-drop-value', String(value))}`);
+}
+/** A complete reference link to another document, such as `TASK-1231` or `TASK-1231#method`. */
+export function ref(target, label) {
+    return raw(`<a href="#" class="adoc-ref" ${attr('data-adoc-ref', target)}>${escapeHtml(label ?? target)}</a>`);
+}
+/** Turns heading text into an anchor value: `Completion Criteria` becomes `completion-criteria`. */
+export function slug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '-')
+        .replace(/^-+|-+$/g, '');
+}
+//# sourceMappingURL=markup.js.map

package/dist/markup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.js","sourceRoot":"","sources":["../src/markup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAG5C,SAAS,IAAI,CAAC,IAAY,EAAE,KAAa;IACvC,OAAO,GAAG,IAAI,KAAK,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;AAC1C,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,MAAM,CAAC,KAAsB;IAC3C,OAAO,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,IAAY;IAC/C,OAAO,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,IAAoG;IACzH,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1I,IAAI,IAAI,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACzD,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAsB;IAC7D,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,KAAc;IAChD,OAAO,GAAG,CAAC,gCAAgC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;AACjH,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,IAAI;SACR,WAAW,EAAE;SACb,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+/** How the files of one document are laid out on disk. */
+export type DocumentLayout = 
+/**
+ * One file named `<KEY>-<local id><extension>`, such as `TODO-gui.md`, and optionally companion files with the same name
+ * and the listed extensions, such as `SKETCH-login.png` beside `SKETCH-login.excalidraw`. Companion files belong to
+ * the document but are not handed to plugin functions, since they may be binary.
+ */
+{
+    kind: 'file';
+    extension: string;
+    companions?: string[];
+}
+/** One folder named `<KEY>-<local id>/` whose main file is `entry`, such as `BUG-42/bug.yaml`. */
+ | {
+    kind: 'folder';
+    entry: string;
+};
+/** One document as adoc hands it to a plugin function. All paths are relative to the workspace root. */
+export interface PluginDocument {
+    /** The document key, such as `TODO-gui`. */
+    readonly key: string;
+    /** The plugin key, such as `TODO`. */
+    readonly pluginKey: string;
+    /** The part of the key after the first hyphen, such as `gui`. */
+    readonly localId: string;
+    /** The file or folder of the document. */
+    readonly path: string;
+    /** The main file: the file itself, or the entry file of a folder document. Use it for source positions. */
+    readonly file: string;
+    /** The text of the main file. Empty when the entry file of a folder document is missing. */
+    readonly text: string;
+    /** Every file of the document by path relative to the document: `{ 'TODO-gui.md': '…' }` or `{ 'bug.yaml': '…', 'notes.md': '…' }`. */
+    readonly files: Readonly<Record<string, string>>;
+}
+/** What `summarize` returns. Shown in the document list and in reference tooltips. */
+export interface DocumentSummary {
+    title: string;
+    /** Free text shown as is, such as `DONE` or `3/5 done`. */
+    status: string;
+    /** Extra rows for the tooltip table. */
+    fields?: Record<string, string | number | boolean>;
+}
+/** A user operation on a control that `action()` marked. */
+export interface ActionEvent {
+    /** `client`: sent by an element of the plugin's client module (`client/index.js`) with the `adoc-action` DOM event. */
+    kind: 'click' | 'toggle' | 'drag' | 'client';
+    /** The action name given to `action()`. */
+    name: string;
+    /** The value given to `action()`. */
+    value: string;
+    /** Toggle only: the new checked state. */
+    checked?: boolean;
+    /** Drag only: the value of the drop target given to `dropTarget()`. */
+    to?: string;
+    /** The nearest enclosing anchor of the control, if any. */
+    anchor?: string;
+}
+/** A file content in an action result: text, or binary data as base64. */
+export type FileContent = string | {
+    base64: string;
+};
+/** What an action handler returns. Every field is optional. */
+export interface ActionResult {
+    /** New text for the main file. */
+    text?: string;
+    /** New contents for files of a folder document, by path relative to the document. */
+    files?: Record<string, FileContent>;
+    /** New contents for companion files of a file document, by extension, such as `{ '.png': { base64 } }`. */
+    companions?: Record<string, FileContent>;
+    /** Text of the message sent to the agent. */
+    message?: string;
+}
+export type ActionHandler = (doc: PluginDocument, event: ActionEvent) => ActionResult | undefined | void;
+/** The object a plugin's `index.ts` default-exports through `definePlugin`. */
+export interface PluginDefinition {
+    /** One line shown by `adoc plugin list`. */
+    description: string;
+    layout: DocumentLayout;
+    summarize(doc: PluginDocument): DocumentSummary;
+    /** Returns the body HTML, usually built with `html` and `markdown`. */
+    render(doc: PluginDocument): HtmlFragment | string;
+    /**
+     * Optional. Returns the body HTML that shows what changed since `previous`, an earlier version of the same document.
+     * Without it, adoc shows a line diff of the main file (see `sourceDiff`).
+     */
+    renderChanges?(doc: PluginDocument, previous: PluginDocument): HtmlFragment | string;
+    /** Handlers by action name. An action without a handler goes to adoc's default handler, which only sends a request to the agent. */
+    actions?: Record<string, ActionHandler>;
+}
+/** Trusted HTML produced by `html`, `raw` and the markup helpers. */
+export declare class HtmlFragment {
+    readonly html: string;
+    constructor(html: string);
+    toString(): string;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/** Trusted HTML produced by `html`, `raw` and the markup helpers. */
+export class HtmlFragment {
+    html;
+    constructor(html) {
+        this.html = html;
+    }
+    toString() {
+        return this.html;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwFA,qEAAqE;AACrE,MAAM,OAAO,YAAY;IACF,IAAI;IAAzB,YAAqB,IAAY;oBAAZ,IAAI;IAAW,CAAC;IACrC,QAAQ;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agent-workshop/adoc-plugin-kit",
+  "version": "0.1.0",
+  "license": "0BSD",
+  "type": "module",
+  "description": "Everything an adoc plugin imports: definePlugin, html, markdown and markup helpers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dirty49374/adoc.git",
+    "directory": "packages/plugin-kit"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./skill/SKILL.md": "./skill/SKILL.md",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "highlight.js": "^11.12.0",
+    "markdown-it": "15.0.2",
+    "yaml": "2.9.0",
+    "zod": "4.5.4"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "check": "tsc -b && tsc -p test",
+    "test": "vitest run --testTimeout 20000"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: adoc-plugin-authoring
+description: "Writes adoc plugins: a folder with index.ts (definePlugin: layout, summarize, render, actions), skill/SKILL.md and optional browser code. Use when creating or changing an adoc plugin or its skill."
+---
+
+# Writing an adoc plugin
+
+A plugin defines one kind of document. It is **one folder with `index.ts` and `skill/SKILL.md`**. No build step: adoc loads `index.ts` directly with Node's type stripping (only a browser `client/`, below, needs one, which you run yourself).
+
+```
+plugins/note/
+  index.ts         ← export default definePlugin({ … })
+  skill/SKILL.md   ← the plugin's agent skill: tells the agent how to edit these documents
+  package.json     ← optional: npm packages it imports, and the plugin-kit range it needs
+  client/          ← optional: browser code (index.js, index.css), see "Browser code"
+```
+
+Put a plugin for one project in `.adoc/plugins/<name>/`, and declare it in the workspace's `.adoc/adoc.yaml` (restart a running `adoc server run` to load it; a restart loses held messages, see "Start: claim" in the adoc skill), then check:
+
+```yaml
+plugins:
+  NOTE: ./plugins/note        # key: uppercase letters only, documents are named NOTE-<local id>.<ext>;
+                              # source: a path from this file, npm:<package> or github:<owner>/<repo>/<folder>
+```
+
+Its scope, and so where `adoc skill install` installs its skill, follows from where the folder is (see "Project scope and user scope" in the adoc skill).
+
+```sh
+adoc plugin list      # shows the plugin, or its load error
+adoc check            # runs summarize and render on every document; exits 1 on errors (warnings do not fail it)
+```
+
+**Publishing.** To share a plugin, publish its folder as an npm package or put it in a GitHub repository (see "Installing plugins" in the adoc skill). Ship it ready to run, since adoc never builds or installs what it fetches: JavaScript `index.js` for npm (Node does not strip types inside `node_modules`; build `index.ts` with esbuild or tsc), the built `client/`, and `skill/`. Declare the plugin-kit range it needs as `"peerDependencies": { "@agent-workshop/adoc-plugin-kit": "^0.1.0" }`: adoc refuses to load it with a plugin-kit outside that range.
+
+Actions run only from the web UI: start `adoc server run`, open a sample document and click, toggle or drag (or use the elements of your client module).
+
+A running `adoc server run` reloads a plugin from a folder outside `node_modules` whenever a file at the top of its folder changes. A reload imports `index.ts` again, but the other files it imports keep their old code: restart the server after changing them.
+
+## What a plugin provides
+
+| field | type | meaning |
+|---|---|---|
+| `description` | `string` | one line for `adoc plugin list` |
+| `layout` | `{ kind: 'file', extension: '.md', companions?: ['.png'] }` or `{ kind: 'folder', entry: 'bug.yaml' }` | a document is the file `NOTE-<local id>.md` (with optional companion files, see below), or the folder `NOTE-<local id>/` with the main file `bug.yaml` |
+| `summarize(doc)` | returns `{ title, status, fields? }` | shown in the list and in reference tooltips; `status` is free text; `fields` values are string, number or boolean, so join lists: `attendees.join(', ')` |
+| `render(doc)` | returns `html\`…\`` | the document body; adoc draws the header (key, title, status) around it, so do not repeat the title |
+| `renderChanges(doc, previous)` | returns `html\`…\`` | optional; the body showing what changed since `previous`, an earlier version that the user saw last. Without it adoc shows a line diff of the main file |
+| `actions` | `{ [name]: (doc, event) => { text?, files?, companions?, message? } }` | optional; see Actions |
+
+The agent skill is not a field: it is the file `skill/SKILL.md` next to `index.ts`, with front matter `name` and `description`; a plugin without it fails to load.
+
+`doc` is `{ key, pluginKey, localId, path, file, text, files }`:
+- `path`: the workspace-relative path of the document itself, the file or the folder;
+- `file`: the workspace-relative path of the main file (the file itself, or the folder's entry file); use it for `source` and `markdown({ file })`;
+- `text`: the main file's text; `files`: the files of the document, read as UTF-8 text: for a folder document every file by path relative to the folder (keep binary files out of folder documents), for a file document the main file under its name (companion files are not in it).
+
+If a function throws, adoc shows the message as the document's error and in `adoc check`; you do not need try/catch.
+
+The main file is written by hand, too: the agent edits it directly, and the user can edit the whole main file in the web UI. Parse it leniently (ignore lines you do not understand, give defaults for missing fields) and throw only when the file cannot be read at all.
+
+## Helpers (`import { … } from '@agent-workshop/adoc-plugin-kit'`)
+
+| helper | use |
+|---|---|
+| `html\`…\`` | build HTML; interpolated values are escaped, arrays are joined, `null`/`undefined`/`false` print nothing |
+| `raw(s)` | insert trusted HTML unescaped, e.g. `${done ? raw('checked') : ''}` |
+| `markdown(text, { file, line })` | Markdown → HTML; `[[KEY]]` becomes a reference; with `file` and `line` (1-based line where `text` starts) every block gets its source position. `{ inline: true }` for one line |
+| `frontmatter(text)` | `{ data, body, bodyLine }` for YAML front matter; `bodyLine` is the 1-based file line of the first body line (the line after the closing `---`), ready for `markdown(body, { file: doc.file, line: bodyLine })`. YAML dates such as `2026-09-24` stay strings |
+| `parseYaml`, `stringifyYaml` | YAML for `.yaml` documents |
+| `anchor(value)` | put inside a start tag: the element can be commented on as `KEY#value` |
+| `source(doc.file, line)` | put inside a start tag: comments on it carry `file:line` |
+| `action({ kind, name, value, confirm? })` | put inside a start tag: `click` on a `<button>`, `toggle` on an `<input type="checkbox">`, `drag` on a draggable element. With `confirm`, the web UI first asks the user that question (each user can turn it off per action), for example when the action asks the agent to start work |
+| `dropTarget(name, value)` | put inside a start tag: a drop zone for the drag action `name` |
+| `ref(key, label?)` | a reference link to another document |
+| `slug(text)` | `'Done when'` → `'done-when'`, handy for section anchors |
+| `diffLines(oldText, newText)` | `[{ op: 'same' \| 'added' \| 'removed', text, line }]` for your own `renderChanges` |
+| `sourceDiff(oldText, newText, { file })` | the line diff adoc shows by default, as HTML |
+| `unifiedDiff(oldText, newText, file, context?)` | a unified diff (`--- a/…`, `+++ b/…`, `@@` hunks) as text, for example for an action's message |
+
+Markup helpers go **inside** start tags: `html\`<li ${anchor(n)} ${source(doc.file, n)}>…</li>\``. Nesting is fine: a section with `anchor()` can contain blocks with their own `source()`; adoc uses the nearest one.
+
+Never add `<script>` or `on…=` attributes; adoc removes them. Every interaction is an action.
+
+## Actions
+
+The user clicks, toggles or drags a control marked with `action()`. adoc calls `actions[name](doc, event)` on the server.
+
+`event` is `{ kind, name, value, checked?, to?, anchor? }`:
+- `kind` is the control type you gave `action()` (`click`, `toggle` or `drag`), or `client` for an `adoc-action` event of your client module; `name` selects the handler; `value` is the value you gave `action()` (or the event's `value`), always as a string;
+- `checked`: the new state, for toggle; `to`: the drop target's value, for drag;
+- `anchor`: the bare value of the nearest enclosing `anchor()`, such as `goal` (not `KEY#goal`).
+
+Return any of:
+- `text`: new text of the main file (adoc writes it, refusing if the file changed since it was shown);
+- `files`: new contents of files in a folder document, by path relative to the folder;
+- `companions`: new contents of companion files of a file document, by extension, such as `{ '.png': { base64 } }`;
+- `message`: text sent to the agent.
+
+Any other key fails the action.
+
+A content is text, or `{ base64 }` for binary data.
+
+A handler sends the agent a message only when it returns `message`: with `applied: true` when adoc also wrote files, with `applied: false` when it wrote nothing (a request: the agent makes the change). A handler that writes without a `message` tells the agent nothing; it sees the change only as an uncommitted edit. When a write is due but the file changed since the user saw it, adoc writes nothing, sends nothing and shows the user why.
+
+**Without a handler** for a name, adoc sends the agent a request `user request: <name> <value>` (for a toggle the value is the new checked state, for a drag `<value> to <to>`) and changes nothing. That is often all you need: the agent then edits the file.
+
+## Companion files
+
+A file document can have companion files: files beside it with the same name and another extension, declared in the layout, such as `layout: { kind: 'file', extension: '.excalidraw', companions: ['.png'] }` for `SKETCH-login.excalidraw` with `SKETCH-login.png`. They belong to the document (its version, its last update, archiving) but are not in `doc`, since they may be binary. An action writes one by returning `companions: { '.png': content }`.
+
+## Browser code: the client module
+
+When HTML is not enough, for example for a drawing board, the plugin brings browser code: the folder `client/` with `index.js` (an ES module with every library bundled in) and optionally `index.css`. adoc serves it at `/assets/plugins/<KEY>/` and loads it once per page. The module defines custom elements, and `render` returns their tags:
+
+```ts
+render: (doc) => html`<adoc-sketch data-adoc-document="${doc.key}" data-adoc-file="${doc.file}"></adoc-sketch>`,
+```
+
+The element talks to adoc only through DOM events and two URLs:
+
+| what | how |
+|---|---|
+| read the main file | `fetch('/api/documents/<key>/file')` → `{ key, version, file, text }` |
+| change files | dispatch `new CustomEvent('adoc-action', { bubbles: true, detail: { name, value, reply } })`; adoc runs the action (kind `client`) with the shown version and calls `reply({ status, version?, reason?, error? })`: `applied` (with the new `version`), `sent`, `refused` (with `reason`), `failed` (with `error`) or `busy` (another action was running: try again). Pass `value` as a string, or it arrives empty |
+| tell the agent | dispatch `new CustomEvent('adoc-draft', { bubbles: true, detail: { text } })`: one draft comment on the document waits in the composer; a later one replaces it |
+| follow changes | `window.addEventListener('adoc-documents-changed', (e) => e.detail.keys…)`: the changed keys, or `['*']` for all (after a plugin reload) |
+
+Keep the `render` output the same across changes of the document (load the content in the element, not in attributes), or the page replaces the element on every change and it loses its state. A `client/` built from sources (with esbuild, for example) is a build output; see the SKETCH plugin for a complete example.
+
+## Styling: classes and design tokens
+
+The web UI styles your HTML; for plain HTML you write no CSS. Its look follows the opencode TUI theme: regions differ by surface (background shade) rather than borders, emphasis is an accent bar on the left edge, and no text is larger than the body text (headings stand out by colour and weight).
+
+**Classes:**
+
+| Class | Use |
+|---|---|
+| `adoc-list` + `adoc-item` | rows; `adoc-done` on an item strikes it through |
+| `adoc-section` | a section, usually with an `<h2>` |
+| `adoc-toolbar` | a row of small buttons and meta text |
+| `adoc-muted` | quiet, smaller meta text |
+| `adoc-chip` | a small label, such as a status or a tag |
+| `adoc-block` | a panel block with an accent bar |
+| `adoc-tone-primary`, `-secondary`, `-accent`, `-success`, `-warning`, `-error`, `-info` | the colour of an `adoc-block` bar or an `adoc-chip` text |
+| `adoc-board` + `adoc-column` + `adoc-column-title` + `adoc-card` | columns of cards; columns wrap instead of scrolling |
+| `adoc-trash` | a removal drop zone |
+| `adoc-added`, `adoc-removed`, `adoc-changed` | marks for `renderChanges` |
+
+Headings, lists, links, tables and code from `markdown()` get the theme's Markdown colours; a fenced code block that names its language (```` ```ts ````) is syntax-highlighted, and a ```` ```mermaid ```` block is drawn as a diagram.
+
+**Design tokens:** when you need a colour in an inline `style="…"`, use a token instead of a literal, so that light and dark both work: `var(--adoc-text)`, `--adoc-text-muted`, `--adoc-surface`, `--adoc-surface-panel`, `--adoc-surface-element`, `--adoc-primary`, `--adoc-secondary`, `--adoc-accent`, `--adoc-success`, `--adoc-warning`, `--adoc-error`, `--adoc-info`, `--adoc-border`, `--adoc-border-subtle`. Sizes: `--adoc-size-base`, `--adoc-size-small`, `--adoc-size-tiny`; fonts: `--adoc-font-text`, `--adoc-font-mono`.
+
+## Rules that avoid load errors
+
+- Import types with `import type { PluginDocument } from '@agent-workshop/adoc-plugin-kit';` (a separate `import type` line). Node strips types; a value import of a type fails.
+- No TypeScript `enum`, `namespace` or parameter properties (`constructor(private x)`): Node cannot strip them.
+- `index.ts` is the entry. It may import other files of the plugin folder (a server restart picks up changes to them, see above), `@agent-workshop/adoc-plugin-kit` (adoc provides it wherever the plugin folder is), Node built-ins, and npm packages listed in the plugin's own `package.json` and installed with `npm install` in the plugin folder.
+- Action names are lowercase kebab-case: `toggle`, `move`, `add-card`. Never name one `archive` or `unarchive`: the document header sends those, and the agent archives or restores the document.
+
+## Complete example: a checklist plugin
+
+A checklist whose boxes the user ticks; the handler writes the tick itself. (The TODO plugin of adoc instead sends a request, so that the agent does the item.)
+
+```ts
+import { action, anchor, definePlugin, html, markdown, raw, source } from '@agent-workshop/adoc-plugin-kit';
+import type { PluginDocument } from '@agent-workshop/adoc-plugin-kit';
+
+const ITEM = /^(\s*)- \[( |x|X)\] (.*)$/;
+
+function parse(doc: PluginDocument) {
+  const lines = doc.text.split('\n');
+  const title = lines.find((l) => l.startsWith('# '))?.slice(2).trim();
+  const items = lines.flatMap((l, i) => {
+    const m = ITEM.exec(l);
+    return m ? [{ line: i + 1, done: m[2] !== ' ', text: m[3]! }] : [];
+  });
+  return { title, items, lines };
+}
+
+export default definePlugin({
+  description: 'A checklist whose boxes the user ticks, as a Markdown task list.',
+  layout: { kind: 'file', extension: '.md' },
+
+  summarize(doc) {
+    const { title, items } = parse(doc);
+    const done = items.filter((i) => i.done).length;
+    return { title: title ?? doc.key, status: `${done}/${items.length} done`, fields: { open: items.length - done, done } };
+  },
+
+  render(doc) {
+    const { items } = parse(doc);
+    return html`
+      <ul class="adoc-list">
+        ${items.map(
+          (item) => html`
+            <li class="adoc-item ${item.done ? 'adoc-done' : ''}" ${anchor(item.line)} ${source(doc.file, item.line)}>
+              <input type="checkbox" ${action({ kind: 'toggle', name: 'toggle', value: item.line })} ${item.done ? raw('checked') : ''} />
+              <span>${markdown(item.text, { inline: true })}</span>
+            </li>`,
+        )}
+      </ul>`;
+  },
+
+  actions: {
+    toggle(doc, event) {
+      const { lines } = parse(doc);
+      const index = Number(event.value) - 1;
+      const m = ITEM.exec(lines[index] ?? '');
+      if (!m) throw new Error(`line ${event.value} is not a task item`);
+      lines[index] = `${m[1]}- [${event.checked ? 'x' : ' '}] ${m[3]}`;
+      return { text: lines.join('\n'), message: `${doc.key}#${event.value} ${event.checked ? 'checked' : 'unchecked'}: ${m[3]}` };
+    },
+  },
+});
+```
+
+## skill/SKILL.md
+
+The plugin's skill is what the agent reads before it touches the plugin's documents, and what the user reads in the web UI (`SKILL.md` beside the plugin key, where they may comment on it or edit it; `adoc skill update` installs a changed one). `adoc skill install` installs the folder `skill/` for the agents the skills CLI detects, so keep only the skill in it, never code.
+
+**Front matter.** `name` is `adoc-` and the plugin key in lowercase. The `description` is all an agent sees when it chooses a skill, so write it in the third person and say what the documents are and **when to use them**, with the words a user would use (the plugin key, the file extension, the kind of work). At most 1024 characters, no XML tags.
+
+**Body.** Cover these, in whatever order and depth fits the plugin and the project:
+
+1. **Purpose:** where these documents are used and what they achieve.
+2. **States and workflow:** the states a document goes through and the recommended flow between them, including who moves it (the agent, or only the user).
+3. **Instructions for the agent:** what to do, what not to do, and what to do when something happens: "do X", "never do Y", "when Z, do W".
+4. **File:** the format, with a short example, and the recommended local id.
+5. **Anchors:** what an anchor is, so that the agent finds a commented place.
+6. **Actions:** for each action, what the plugin already did and what the agent is expected to do.
+
+Write it short (the agent is capable; explain only what it cannot know), use one term for one thing throughout, and leave out what goes stale, such as dates or current counts.
+
+Here is a sensible starting point; it is an example only, so change, drop or add sections to suit the plugin and the project:
+
+```markdown
+---
+name: adoc-review
+description: "REVIEW documents: one code review each, with its findings and their resolution. Use when the user asks for a review, comments on a finding, or wants to know what is still open before a release."
+---
+
+# REVIEW documents
+
+Document keys look like `REVIEW-<local id>`. Read the general workflow with `adoc skill view adoc`.
+
+## Purpose
+One REVIEW records the review of one change: what was looked at, each finding, and how it was resolved, so that nothing found in a review is lost.
+
+## States and workflow
+`OPEN` → `ANSWERED` → `CLOSED`. You open a review and answer findings; only the user closes it.
+
+## Instructions
+- Write one finding per `##` section, with the file and line it concerns.
+- Never delete a finding; mark it resolved and say how.
+- When a comment disagrees with a finding, answer it under the finding and keep the review `ANSWERED`.
+
+## File
+`REVIEW-<local id>.md`: front matter `title`, `status`, then one `##` section per finding. Recommended local id: today's date (yymmdd) and a title, such as `REVIEW-261002-login-form`.
+
+## Anchors
+The anchor of a finding is its heading in lowercase with hyphens: `REVIEW-…#sql-in-loop`.
+
+## Actions
+| action | what adoc already did | what you do |
+|---|---|---|
+| `resolve` | nothing (`applied: false`) | mark the finding resolved, as the user asks |
+```