@heart-of-gold/toolkit 0.1.36 → 0.1.38

package/.claude-plugin/marketplace.json

@@ -15,19 +15,19 @@
       "name": "deep-thought",
       "source": "./plugins/deep-thought",
       "description": "The Answer Computer — reasoning tools for brainstorming, planning, and deep thinking",
-      "version": "0.2.6"
+      "version": "0.2.8"
     },
     {
       "name": "marvin",
       "source": "./plugins/marvin",
       "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
-      "version": "0.3.6"
+      "version": "0.3.8"
     },
     {
       "name": "babel-fish",
       "source": "./plugins/babel-fish",
       "description": "Universal Translator — media generation tools for audio, image, and video content",
-      "version": "0.2.4"
+      "version": "0.2.6"
     },
     {
       "name": "quellis",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {

package/plugins/babel-fish/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-fish",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Universal Translator — media generation tools for audio, image, video, and visualization",
   "author": {
     "name": "ondrej-svec",

package/plugins/babel-fish/skills/visualize/SKILL.md

@@ -120,6 +120,26 @@ Apply these defaults unless the user asks for something else:
 See also:
 - `docs/architecture/visualize-design-rules.md`
 
+## Writing Tone
+
+Write artifact copy like a strong product/design-systems editor:
+- concise
+- confident
+- specific
+- implementation-aware
+- high signal-to-noise
+
+Prefer lines like:
+- `One code change, bounded migration risk`
+- `Three priority tiers, one direction`
+- `Deferred — tracked, not scheduled`
+
+Avoid:
+- fluffy marketing copy
+- generic AI hype
+- long throat-clearing intros
+- repeating the source document verbatim
+
 ## Rules: Do
 
 - Decide the communication goal before choosing the renderer.
@@ -130,6 +150,7 @@ See also:
 - Use `roadmap` or richer execution-oriented views for plans when that improves understanding.
 - Use `architecture` views for system/design-heavy documents.
 - Keep raw source detail available, but secondary.
+- Make section labels do real editorial work: `Scope at a glance`, `Why this shape`, `What could go wrong`, `Deferred — tracked, not scheduled`.
 - Briefly explain why you chose the visualization mode when sharing the result.
 
 ## Rules: Don't
@@ -141,6 +162,8 @@ See also:
 - Do not use flashy gradients, glass, shadows, or color noise unless they clearly improve hierarchy.
 - Do not silently guess when the visualization choice is materially ambiguous.
 - Do not create multiple competing artifacts unless the user explicitly asks for comparison.
+- Do not preserve source heading order if a clearer narrative order exists.
+- Do not expose every extracted detail at the same visual weight.
 
 ## Expected Behavior
 
@@ -233,14 +256,22 @@ fi
 
 When quality matters more than speed, start from the shared authored-artifact template, write the HTML directly, then publish it.
 
+**Cross-platform preferred path:** use the Node helpers first. They work better across macOS, Linux, Windows, Codex, Claude Code, and Pi than shell-specific one-liners.
+
 ```bash
-HTML_OUT="$(bash "$(dirname "$SCRIPT")/new-authored-artifact.sh")"
-# edit the generated template at $HTML_OUT
-bash "$(dirname "$SCRIPT")/publish-authored-html.sh" --url-only "$HTML_OUT"
+# 1. Print a fresh temp HTML path based on the shared template
+node /absolute/path/to/new-authored-artifact.js
+
+# 2. After editing the file, publish it
+node /absolute/path/to/publish-authored-html.js --url-only /tmp/path/from-step-1/artifact.html
 ```
 
+**Shell fallback:** if Node helper usage is awkward in a specific harness, the `.sh` helpers are still available.
+
 Template and helper files:
 - `scripts/agent-artifact-template.html`
+- `scripts/new-authored-artifact.js`
+- `scripts/publish-authored-html.js`
 - `scripts/new-authored-artifact.sh`
 - `scripts/publish-authored-html.sh`
 
@@ -266,18 +297,21 @@ node "$(dirname "$SCRIPT")/render-mindmap/index.js" --html /tmp/map.html path/to
 
 Use this when the artifact needs stronger design judgment than the fallback renderer can provide.
 
-1. Create the scaffold:
+1. Create the scaffold with a standalone cross-platform command:
    ```bash
-   HTML_OUT="$(bash "$(dirname "$SCRIPT")/new-authored-artifact.sh")"
+   node /absolute/path/to/new-authored-artifact.js
    ```
-2. Author the HTML artifact directly into that file.
-3. Publish it:
+2. Read the printed temp path from stdout.
+3. Author the HTML artifact directly into that file.
+4. Publish it with a standalone cross-platform command:
    ```bash
-   bash "$(dirname "$SCRIPT")/publish-authored-html.sh" --url-only "$HTML_OUT"
+   node /absolute/path/to/publish-authored-html.js --url-only /tmp/your-artifact.html
    ```
-4. Read the returned URL from stdout.
-5. Return that URL to the user as the primary result.
-6. Briefly explain what was published and why this visual form was chosen.
+5. Read the returned URL from stdout.
+6. Return that URL to the user as the primary result.
+7. Briefly explain what was published and why this visual form was chosen.
+
+Shell helpers remain available as a fallback if a harness prefers `bash`.
 
 ### Fallback share flow: render then publish
 
@@ -328,16 +362,27 @@ When authoring HTML directly, follow this sequence:
 
 1. Read the source and decide the artifact family.
 2. Decide the audience and the first question the page should answer.
-3. Create the scaffold with `new-authored-artifact.sh`.
-4. Replace the template content with a real designed artifact.
-5. Keep source detail secondary.
-6. Publish with `publish-authored-html.sh`.
+3. Create the scaffold with `new-authored-artifact.js` or `new-authored-artifact.sh`.
+4. Draft the page in three layers:
+   - **summary layer** — what matters first
+   - **decision / execution layer** — the main story
+   - **source layer** — appendix, evidence, or raw detail
+5. Replace the template content with a real designed artifact.
+6. Keep source detail secondary.
+7. Publish with `publish-authored-html.js` or `publish-authored-html.sh`.
+
+Harness note:
+- prefer separate commands over complex one-liners
+- prefer the Node helpers for cross-platform behavior
+- avoid assuming `mktemp /tmp/name-XXXXXX.html` works on every shell; use the provided helper instead
+- if a harness only supports shell comfortably, use the `.sh` helpers as fallback
 
 For plans specifically:
 - do not dump the full task prose into the primary lanes
 - summarize workstreams into short cards or task tiles
 - show dependencies, risks, and acceptance separately
 - keep raw markdown only in an appendix or disclosure block
+- compress long task descriptions into one-sentence operational summaries first
 
 ## Required Output Structure
 
@@ -369,6 +414,53 @@ For substantial HTML artifacts, prefer this structure:
 - what happens next
 - supporting source detail below
 
+## Expected Behavior by Artifact Family
+
+### Plan / roadmap artifacts
+Must usually include:
+- a top-line mission
+- scope or execution stats
+- grouped workstreams or phases
+- key decisions / rationale
+- explicit risks / acceptance posture
+- deferred or out-of-scope work if relevant
+
+### Architecture artifacts
+Must usually include:
+- system framing
+- major components / boundaries
+- integration or dependency context
+- key tradeoffs / decisions
+- assumptions / risks
+
+### Explainers
+Must usually include:
+- what this is
+- why it matters
+- the recommendation or conclusion
+- supporting evidence
+- what happens next
+
+## Recommended Authoring Moves
+
+When the artifact still feels too markdown-like, do one or more of these:
+- replace raw section names with editorial section labels
+- compress paragraphs into 1–3 sentence summary cards
+- convert repeated prose into chips, bullets, metrics, or compact lists
+- surface one key takeaway per section before the detail
+- split `what / why / risk / next` into separate visual units
+- move citations, raw notes, and source text into a secondary appendix
+
+## Guideline Authoring Workflow
+
+1. Restate the artifact purpose in one sentence.
+2. Decide the audience and primary question.
+3. Choose the artifact family and page shape.
+4. Extract only what is needed for the summary layer.
+5. Build the main body around grouped visual units, not source sections.
+6. Add source appendix or evidence only after the main page works.
+7. Run the quality gates before publishing.
+
 ## Quality Gates
 
 Before returning a shared HTML result, check mentally:
@@ -380,9 +472,37 @@ Before returning a shared HTML result, check mentally:
 - Is the chosen mode actually appropriate for the content?
 - If this is a plan, does it foreground execution rather than document order?
 - If this is a brainstorm, is it actually branch-shaped enough for a mind map?
+- Do the section titles help scanning?
+- Is secondary detail actually secondary?
 
 If the answer to several of these is no, reconsider the mode or ask the user.
 
+## Pattern Examples
+
+### Good plan framing
+- `Scope at a glance`
+- `Three priority tiers, one direction`
+- `What could go wrong`
+- `Deferred — tracked, not scheduled`
+
+### Good risk cards
+- short risk title
+- severity or posture badge
+- one-sentence mitigation
+- accepted vs mitigated distinction when relevant
+
+### Good summary stats
+- workstreams
+- tasks
+- code edits
+- new files
+- doctrine docs touched
+
+### Good appendix behavior
+- source plan path
+- cited references
+- raw plan or evidence hidden behind disclosure
+
 ## Input Formats
 
 ### Markdown (primary)

package/plugins/babel-fish/skills/visualize/scripts/new-authored-artifact.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { copyFileSync, mkdirSync, mkdtempSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatePath = join(__dirname, 'agent-artifact-template.html');
+const providedPath = process.argv[2] ? resolve(process.argv[2]) : null;
+
+const outPath = (() => {
+  if (providedPath) return providedPath;
+  const tempDir = mkdtempSync(join(tmpdir(), 'hog-visualize-artifact-'));
+  return join(tempDir, 'artifact.html');
+})();
+
+mkdirSync(dirname(outPath), { recursive: true });
+copyFileSync(templatePath, outPath);
+process.stdout.write(`${outPath}\n`);

package/plugins/babel-fish/skills/visualize/scripts/new-authored-artifact.sh

@@ -6,7 +6,8 @@ TEMPLATE="$SCRIPT_DIR/agent-artifact-template.html"
 OUT_PATH="${1:-}"
 
 if [[ -z "$OUT_PATH" ]]; then
-  OUT_PATH="$(mktemp /tmp/hog-visualize-artifact-XXXXXX.html)"
+  TEMP_BASE="$(mktemp /tmp/hog-visualize-artifact-XXXXXX)"
+  OUT_PATH="${TEMP_BASE}.html"
 fi
 
 cp "$TEMPLATE" "$OUT_PATH"

package/plugins/babel-fish/skills/visualize/scripts/publish-authored-html.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+function fail(code, message, status = 1) {
+  process.stdout.write(`${JSON.stringify({ ok: false, error: { code, message } })}\n`);
+  process.exit(status);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    htmlPath: null,
+    configPath: resolve(homedir(), '.agent-share', 'config.json'),
+    slug: '',
+    title: '',
+    alias: '',
+    urlOnly: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--config' && i + 1 < argv.length) opts.configPath = resolve(argv[++i]);
+    else if (arg === '--slug' && i + 1 < argv.length) opts.slug = argv[++i];
+    else if (arg === '--title' && i + 1 < argv.length) opts.title = argv[++i];
+    else if (arg === '--alias' && i + 1 < argv.length) opts.alias = argv[++i];
+    else if (arg === '--url-only') opts.urlOnly = true;
+    else if (arg === '--help') {
+      process.stdout.write('Usage: publish-authored-html.js <html-file> [--config PATH] [--slug STEM] [--title TITLE] [--alias ALIAS] [--url-only]\n');
+      process.exit(0);
+    } else if (!arg.startsWith('-') && !opts.htmlPath) {
+      opts.htmlPath = resolve(arg);
+    } else {
+      fail('INVALID_ARGS', `Unknown or misplaced argument: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (!opts.htmlPath) fail('MISSING_PATH', 'HTML file path is required.');
+  if (!existsSync(opts.configPath)) fail('MISSING_CONFIG', 'Share server config not found. Run share-server-setup first.');
+  if (!existsSync(opts.htmlPath)) fail('MISSING_PATH', `HTML file does not exist: ${opts.htmlPath}`);
+  if (!opts.htmlPath.toLowerCase().endsWith('.html')) fail('UNSUPPORTED_ARTIFACT', 'Only .html files are supported for authored artifact publishing.');
+
+  const cfg = JSON.parse(readFileSync(opts.configPath, 'utf8'));
+  const apiUrl = String(cfg?.server?.apiUrl || '').replace(/\/$/, '');
+  if (!apiUrl) fail('INVALID_CONFIG', 'share server apiUrl missing from config.');
+
+  const htmlBuffer = readFileSync(opts.htmlPath);
+  const form = new FormData();
+  form.append('artifact', new Blob([htmlBuffer], { type: 'text/html' }), basename(opts.htmlPath));
+  form.append('artifactType', 'html-file');
+  if (opts.slug) form.append('slug', opts.slug);
+  if (opts.title) form.append('title', opts.title);
+  if (opts.alias) form.append('alias', opts.alias);
+
+  const response = await fetch(`${apiUrl}/publish`, { method: 'POST', body: form });
+  const text = await response.text();
+
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    fail('INVALID_RESPONSE', `Share server returned non-JSON response: ${text}`, 1);
+  }
+
+  if (!response.ok || payload?.ok === false) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exit(1);
+  }
+
+  if (opts.urlOnly) {
+    process.stdout.write(`${payload.url || payload.viewerUrl || ''}\n`);
+    return;
+  }
+
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+main().catch((error) => {
+  fail('PUBLISH_FAILED', error instanceof Error ? error.message : String(error));
+});

package/plugins/deep-thought/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-thought",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "The Answer Computer — reasoning tools for brainstorming, planning, architecture design, and deep thinking",
   "author": {
     "name": "ondrej-svec",

package/plugins/marvin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "marvin",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "The Paranoid Android — quality tools for code review, knowledge compounding, and work execution",
   "author": {
     "name": "ondrej-svec",

package/plugins/marvin/skills/share-server-control/SKILL.md

@@ -59,6 +59,16 @@ bash scripts/enable-viewer.sh --public-base-url "https://<machine>.<tailnet>.ts.
 bash scripts/disable-viewer.sh
 ```
 
+### Delete a published artifact by slug
+```bash
+heart-of-gold share-server delete <slug>
+```
+
+### Delete only an alias pointer
+```bash
+heart-of-gold share-server delete --alias <alias> --onlyAlias
+```
+
 ## Notes
 
 - In v1, lifecycle control assumes the reference server was installed as a macOS LaunchAgent.
@@ -73,6 +83,8 @@ bash scripts/disable-viewer.sh
 - `scripts/restart.sh` — restart the LaunchAgent cleanly
 - `scripts/enable-viewer.sh` — enable private Tailscale Serve exposure for the viewer listener
 - `scripts/disable-viewer.sh` — turn off private Tailscale Serve exposure
+- `heart-of-gold share-server delete <slug>` — remove a published artifact, its aliases, and its metadata entries
+- `heart-of-gold share-server delete --alias <alias> --onlyAlias` — remove only an alias pointer
 
 ## References
 

package/share-server/README.md

@@ -59,6 +59,18 @@ bun share-server/src/index.ts init
 bun share-server/src/index.ts health
 ```
 
+### Delete a published share
+
+```bash
+heart-of-gold share-server delete <slug>
+```
+
+### Delete only an alias pointer
+
+```bash
+heart-of-gold share-server delete --alias <alias> --onlyAlias
+```
+
 ### Install stable local server files
 
 ```bash
@@ -93,6 +105,19 @@ curl -fsS -X POST \
   http://127.0.0.1:4815/publish
 ```
 
+## Cleanup model
+
+Artifacts are immutable when published, but the admin surface can remove them when cleanup is needed.
+
+Supported cleanup operations:
+- delete a share by slug
+- delete an alias pointer without deleting the underlying artifact
+
+Deleting a share removes:
+- the artifact directory
+- any aliases pointing at that slug
+- matching metadata entries in `metadata/shares.jsonl`
+
 ## Security model
 
 - publish/admin API binds to localhost only

package/share-server/src/index.ts

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, platform } from "node:os";
 import { ensureConfigAndDataDirs, loadConfig, resolveConfigPath, writeConfig } from "./config";
 import { publishArtifact } from "./publish";
-import { ensureStorageLayout } from "./storage";
+import { deleteAlias, deleteArtifact, ensureStorageLayout, readAlias, readMetadata, removeAliasesForSlug, rewriteMetadata } from "./storage";
 import { createViewerHandler } from "./viewer";
 import type { HealthResponse } from "./types";
 
@@ -92,14 +92,7 @@ async function startServer(flags: Record<string, string | boolean>): Promise<voi
       }
 
       if (request.method === "GET" && url.pathname === "/shares") {
-        const sharesPath = join(dataRoot, "metadata", "shares.jsonl");
-        const text = existsSync(sharesPath) ? await Bun.file(sharesPath).text() : "";
-        const items = text
-          .split(/\r?\n/)
-          .map((line) => line.trim())
-          .filter(Boolean)
-          .map((line) => JSON.parse(line));
-        return Response.json({ ok: true, items });
+        return Response.json({ ok: true, items: readMetadata(dataRoot) });
       }
 
       if (request.method === "POST" && url.pathname === "/publish") {
@@ -127,6 +120,39 @@ async function startServer(flags: Record<string, string | boolean>): Promise<voi
         }
       }
 
+      if (request.method === "DELETE" && url.pathname.startsWith("/shares/")) {
+        const slug = decodeURIComponent(url.pathname.replace(/^\/shares\//, "")).trim();
+        if (!slug) {
+          return Response.json({ ok: false, error: { code: "MISSING_SLUG", message: "Share slug is required." } }, { status: 400 });
+        }
+
+        const removedArtifact = deleteArtifact(dataRoot, slug);
+        const removedAliases = removeAliasesForSlug(dataRoot, slug);
+        const existing = readMetadata(dataRoot);
+        const filtered = existing.filter((record) => record.slug !== slug);
+        const metadataRemoved = filtered.length !== existing.length;
+        rewriteMetadata(dataRoot, filtered);
+
+        if (!removedArtifact && !metadataRemoved && removedAliases.length === 0) {
+          return Response.json({ ok: false, error: { code: "NOT_FOUND", message: `Share not found: ${slug}` } }, { status: 404 });
+        }
+
+        return Response.json({ ok: true, slug, removedArtifact, removedAliases, metadataRemoved });
+      }
+
+      if (request.method === "DELETE" && url.pathname.startsWith("/aliases/")) {
+        const alias = decodeURIComponent(url.pathname.replace(/^\/aliases\//, "")).trim();
+        if (!alias) {
+          return Response.json({ ok: false, error: { code: "MISSING_ALIAS", message: "Alias is required." } }, { status: 400 });
+        }
+        const slug = readAlias(dataRoot, alias);
+        const removed = deleteAlias(dataRoot, alias);
+        if (!removed) {
+          return Response.json({ ok: false, error: { code: "NOT_FOUND", message: `Alias not found: ${alias}` } }, { status: 404 });
+        }
+        return Response.json({ ok: true, alias, slug, removed: true });
+      }
+
       return Response.json({ ok: false, error: { code: "INVALID_REQUEST", message: "Unknown route" } }, { status: 404 });
     },
   });

package/share-server/src/storage.ts

@@ -39,23 +39,81 @@ export function artifactPath(dataRoot: string, slug: string): string {
   return join(artifactsDir(dataRoot), slug);
 }
 
+export function metadataFilePath(dataRoot: string): string {
+  return join(metadataDir(dataRoot), "shares.jsonl");
+}
+
 export function writeMetadata(dataRoot: string, record: ShareRecord): void {
-  const filePath = join(metadataDir(dataRoot), "shares.jsonl");
+  const filePath = metadataFilePath(dataRoot);
   writeFileSync(filePath, `${JSON.stringify(record)}\n`, { flag: "a" });
 }
 
+export function readMetadata(dataRoot: string): ShareRecord[] {
+  const filePath = metadataFilePath(dataRoot);
+  if (!existsSync(filePath)) return [];
+  return readFileSync(filePath, "utf-8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as ShareRecord);
+}
+
+export function rewriteMetadata(dataRoot: string, records: ShareRecord[]): void {
+  const filePath = metadataFilePath(dataRoot);
+  const content = records.map((record) => JSON.stringify(record)).join("\n");
+  writeFileSync(filePath, `${content}${content ? "\n" : ""}`, "utf-8");
+}
+
 export function writeAlias(dataRoot: string, alias: string, slug: string): void {
   const aliasPath = join(aliasesDir(dataRoot), `${slugify(alias)}.json`);
   writeFileSync(aliasPath, `${JSON.stringify({ alias: slugify(alias), slug }, null, 2)}\n`, "utf-8");
 }
 
+export function aliasPath(dataRoot: string, alias: string): string {
+  return join(aliasesDir(dataRoot), `${slugify(alias)}.json`);
+}
+
 export function readAlias(dataRoot: string, alias: string): string | null {
-  const aliasPath = join(aliasesDir(dataRoot), `${slugify(alias)}.json`);
-  if (!existsSync(aliasPath)) return null;
-  const parsed = JSON.parse(readFileSync(aliasPath, "utf-8")) as { slug?: string };
+  const filePath = aliasPath(dataRoot, alias);
+  if (!existsSync(filePath)) return null;
+  const parsed = JSON.parse(readFileSync(filePath, "utf-8")) as { slug?: string };
   return parsed.slug ?? null;
 }
 
+export function deleteAlias(dataRoot: string, alias: string): boolean {
+  const filePath = aliasPath(dataRoot, alias);
+  if (!existsSync(filePath)) return false;
+  rmSync(filePath, { force: true });
+  return true;
+}
+
+export function removeAliasesForSlug(dataRoot: string, slug: string): string[] {
+  const removed: string[] = [];
+  const root = aliasesDir(dataRoot);
+  if (!existsSync(root)) return removed;
+  for (const entry of readdirSync(root)) {
+    if (!entry.endsWith('.json')) continue;
+    const filePath = join(root, entry);
+    try {
+      const parsed = JSON.parse(readFileSync(filePath, 'utf-8')) as { alias?: string; slug?: string };
+      if (parsed.slug === slug) {
+        rmSync(filePath, { force: true });
+        removed.push(parsed.alias ?? entry.replace(/\.json$/, ''));
+      }
+    } catch {
+      // ignore malformed alias records during cleanup
+    }
+  }
+  return removed;
+}
+
+export function deleteArtifact(dataRoot: string, slug: string): boolean {
+  const path = artifactPath(dataRoot, slug);
+  if (!existsSync(path)) return false;
+  rmSync(path, { recursive: true, force: true });
+  return true;
+}
+
 export function copyDirectoryContents(sourceDir: string, destinationDir: string): void {
   mkdirSync(destinationDir, { recursive: true });
   for (const entry of readdirSync(sourceDir)) {

package/src/commands/share-server.ts

@@ -2,6 +2,8 @@ import { defineCommand } from "citty";
 import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { dataRootForConfig } from "../../share-server/src/config";
+import { deleteAlias, deleteArtifact, readAlias, readMetadata, removeAliasesForSlug, rewriteMetadata } from "../../share-server/src/storage";
 
 function packageRoot(): string {
   let dir = dirname(new URL(import.meta.url).pathname);
@@ -86,6 +88,48 @@ export const shareServerCommand = defineCommand({
         console.log(JSON.stringify({ ok: true, serverDir: targetDir }, null, 2));
       },
     }),
+    delete: defineCommand({
+      meta: { name: "delete", description: "Delete a published share by slug, or remove an alias" },
+      args: {
+        slug: { type: "positional", required: false },
+        alias: { type: "string", required: false },
+        config: { type: "string", required: false },
+        onlyAlias: { type: "boolean", required: false },
+      },
+      run({ args }) {
+        const dataRoot = dataRootForConfig(args.config ? String(args.config) : undefined);
+
+        if (args.alias && args.onlyAlias) {
+          const alias = String(args.alias);
+          const slug = readAlias(dataRoot, alias);
+          const removed = deleteAlias(dataRoot, alias);
+          console.log(JSON.stringify(removed
+            ? { ok: true, alias, slug, removed: true }
+            : { ok: false, error: { code: "NOT_FOUND", message: `Alias not found: ${alias}` } }
+          ));
+          process.exit(removed ? 0 : 1);
+        }
+
+        const slug = args.slug ? String(args.slug) : undefined;
+        if (!slug) {
+          console.error("share-server delete requires either <slug> or --alias <alias> --onlyAlias");
+          process.exit(1);
+        }
+
+        const removedArtifact = deleteArtifact(dataRoot, slug);
+        const removedAliases = removeAliasesForSlug(dataRoot, slug);
+        const existing = readMetadata(dataRoot);
+        const filtered = existing.filter((record) => record.slug !== slug);
+        const metadataRemoved = filtered.length !== existing.length;
+        rewriteMetadata(dataRoot, filtered);
+        const ok = removedArtifact || metadataRemoved || removedAliases.length > 0;
+        console.log(JSON.stringify(ok
+          ? { ok: true, slug, removedArtifact, removedAliases, metadataRemoved }
+          : { ok: false, error: { code: "NOT_FOUND", message: `Share not found: ${slug}` } }
+        ));
+        process.exit(ok ? 0 : 1);
+      },
+    }),
     "install-launch-agent": defineCommand({
       meta: { name: "install-launch-agent", description: "Write a macOS LaunchAgent for the installed reference server" },
       args: {