@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/documentation-audiences.json

@@ -0,0 +1,468 @@
+{
+  "version": 1,
+  "scope": {
+    "trackedPatterns": [
+      "*.md",
+      "*.mdx",
+      "*.rst",
+      "*.txt",
+      "docs/examples/*"
+    ],
+    "description": "Tracked Markdown-like prose, including symlinked aliases, plus copyable documentation examples. Script headers, executable configuration, generated JSON evidence, and legal text keep their existing code/config/legal owners."
+  },
+  "allowedAudiences": [
+    "public-product",
+    "operator-current",
+    "operator-example",
+    "maintainer-architecture",
+    "maintainer-verification",
+    "agent-runtime"
+  ],
+  "setupAudiences": [
+    "public-product",
+    "operator-current",
+    "operator-example"
+  ],
+  "readmeSetupTargets": [
+    "docs/configuration.md",
+    "docs/wedge-alarm.md",
+    ".agents/skills/herdr-panes/assets/tmux-backend.md",
+    ".agents/skills/herdr-panes/assets/herdr-backend.md",
+    "docs/zellij-backend.md",
+    "docs/orca-backend.md",
+    "docs/cmux-backend.md",
+    "docs/remote-secondmates.md"
+  ],
+  "requiredOwnerPointers": [
+    {
+      "source": ".agents/skills/firstmate-coding-guidelines/SKILL.md",
+      "target": "docs/documentation-audiences.md"
+    },
+    {
+      "source": ".no-mistakes.yaml",
+      "target": "docs/documentation-audiences.md"
+    },
+    {
+      "source": "CONTRIBUTING.md",
+      "target": "docs/documentation-audiences.md"
+    },
+    {
+      "source": "README.md",
+      "target": "docs/documentation-audiences.md"
+    },
+    {
+      "source": "docs/documentation-audiences.md",
+      "target": "docs/documentation-audiences.json"
+    },
+    {
+      "source": "docs/calm.md",
+      "target": "docs/calm-mode-feasibility.md"
+    },
+    {
+      "source": "docs/calm-mode-feasibility.md",
+      "target": "docs/calm.md"
+    },
+    {
+      "source": "docs/sessionstart-nudge.md",
+      "target": "docs/verification/supervision.md"
+    },
+    {
+      "source": "docs/turnend-guard.md",
+      "target": "docs/verification/supervision.md"
+    },
+    {
+      "source": "docs/watcher-continuity.md",
+      "target": "docs/verification/supervision.md"
+    },
+    {
+      "source": "docs/wedge-alarm.md",
+      "target": "docs/verification/supervision.md"
+    },
+    {
+      "source": ".agents/skills/herdr-panes/assets/tmux-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": ".agents/skills/herdr-panes/assets/herdr-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": "docs/zellij-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": "docs/orca-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": "docs/cmux-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": "docs/codex-app-backend.md",
+      "target": "docs/verification/runtime-backends.md"
+    },
+    {
+      "source": "docs/trace-context.md",
+      "target": "docs/verification/trace-context.md"
+    }
+  ],
+  "surfaces": [
+    {
+      "path": ".agents/skills/afk/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/ahoy/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/ask-user-authority/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/bearings/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/bootstrap-diagnostics/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/captain-hold-lifecycle/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/decision-hold-lifecycle/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/diagnostic-reasoning/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/firstmate-codexapp/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/firstmate-coding-guidelines/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/firstmate-orca/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/fmx-respond/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/common/control-and-recovery.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/common/dispatch.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/common/model-and-effort.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/common/primary-hooks.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/claude.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/codex.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/cursor.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/grok.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/kimi.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/muse.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/opencode.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/harness-adapters/references/harness/pi.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/process-event-sources/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/project-management/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/quota-array-dispatch/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/secondmate-provisioning/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/stow/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/stuck-crewmate-recovery/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/updatefirstmate/SKILL.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".greptile/rules.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "AGENTS.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "CLAUDE.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "CONTRIBUTING.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "GROK_BOT.md",
+      "audience": "public-product"
+    },
+    {
+      "path": "README.md",
+      "audience": "public-product"
+    },
+    {
+      "path": "VISION.md",
+      "audience": "public-product"
+    },
+    {
+      "path": ".agents/skills/eindri-homes/assets/control-plane.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/architecture.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/arm-pretool-check.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/calm-mode-feasibility.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/calm.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/cd-guard.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/cmux-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/codex-app-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/configuration.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/captain-hold-lifecycle.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/documentation-audiences.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/extension-bindings.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/examples/crew-dispatch.json",
+      "audience": "operator-example"
+    },
+    {
+      "path": "docs/examples/process-event-extension/file-signal.mjs",
+      "audience": "operator-example"
+    },
+    {
+      "path": "docs/examples/process-event-extension/firstmate-extension.json",
+      "audience": "operator-example"
+    },
+    {
+      "path": "docs/examples/watched-tools.json",
+      "audience": "operator-example"
+    },
+    {
+      "path": "docs/examples/wedge-alarm",
+      "audience": "operator-example"
+    },
+    {
+      "path": "docs/fm-test-isolation-proof.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/fm-test-portable-shards.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/gitlab-merge-watch.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": ".agents/skills/herdr-panes/assets/herdr-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/orca-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/pi-supervision-branch.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/remote-secondmates.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/scripts.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/sessionstart-nudge.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/subagent-guard.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/supervision-protocols/claude.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/codex.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/cursor.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/grok.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/opencode.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/pi.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": "docs/supervision-protocols/unknown.md",
+      "audience": "agent-runtime"
+    },
+    {
+      "path": ".agents/skills/herdr-panes/assets/tmux-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/trace-context.md",
+      "audience": "maintainer-architecture"
+    },
+    {
+      "path": "docs/turnend-guard.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/verification/dispatch-auth.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/muse.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/process-event-sources.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/public-followup.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/runtime-backends.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/stow-memory.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/supervision.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/verification/trace-context.md",
+      "audience": "maintainer-verification"
+    },
+    {
+      "path": "docs/voice-relay.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/watcher-continuity.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/wedge-alarm.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "docs/zellij-backend.md",
+      "audience": "operator-current"
+    },
+    {
+      "path": "skills/stow/SKILL.md",
+      "audience": "public-product"
+    }
+  ]
+}

package/assets/reference/docs/documentation-audiences.md

@@ -0,0 +1,28 @@
+# Documentation audiences
+
+[`documentation-audiences.json`](documentation-audiences.json) is the machine-consumed classification owner for every maintained prose surface.
+`bin/fm-doc-audience-check.sh` validates exact inventory coverage, README setup routing, required owner pointers, and local link targets.
+Audience metadata is centralized there rather than copied into front matter on every page.
+
+The audience classes have one placement purpose each:
+
+- `public-product` introduces the product or provides standalone public material.
+- `operator-current` explains current behavior, setup, supported limits, stable invariants, concise rationale, and current verification entry points.
+- `operator-example` is copyable current setup material.
+- `maintainer-architecture` explains stable ownership, extension points, mechanism boundaries, and safety rationale for contributors.
+- `maintainer-verification` records repeatable evidence for an active guarantee and may include dates, versions, exact commands, and exact output.
+- `agent-runtime` is loaded or rendered as an operating contract for Firstmate agents rather than read as product documentation.
+
+The knowledge-placement policy is owned by [`firstmate-coding-guidelines`](../.agents/skills/firstmate-coding-guidelines/SKILL.md).
+Task-specific chronology, delivery transcripts, temporary paths, branches, failed hypotheses, and one-off process identifiers stay in private task reports or PR evidence by default.
+Before removing that evidence from a tracked page, distill every unique current fact into its classified owner and retain a focused regression pointer.
+
+Run the structural check directly with:
+
+```sh
+bin/fm-doc-audience-check.sh
+```
+
+The check intentionally does not lint dates, versions, commands, paths, incident language, or transcript-like prose.
+Those forms are legitimate in maintainer verification and require semantic review rather than keyword heuristics.
+For every changed prose surface, review its audience, authoritative owner, current relevance, evidence destination, and unique safety facts, then repeat that review over the complete branch diff after all fixes.

package/assets/reference/docs/examples/crew-dispatch.json

@@ -0,0 +1,26 @@
+{
+  "rules": [
+    {
+      "when": "The task depends on fresh news, current events, live public facts, or recent market and product changes.",
+      "use": { "harness": "grok" },
+      "why": "Grok is the preferred dispatch when current web-connected context is central to the work."
+    },
+    {
+      "when": "The task is a trivial mechanical edit such as a rote rename, formatting sweep, targeted typo fix, or simple file gathering.",
+      "use": { "harness": "claude", "model": "haiku", "effort": "low" },
+      "why": "Use the cheapest fast profile when the task is narrow and low ambiguity."
+    },
+    {
+      "when": "The task is a big or ambiguous multi-file feature, a risky refactor, or work that requires holding many moving parts in mind.",
+      "use": [
+        { "harness": "claude", "model": "claude-sonnet-5", "effort": "high" },
+        { "harness": "codex", "model": "gpt-5.5", "effort": "high" }
+      ],
+      "why": "Use a strong coding profile for big, ambiguous work; resolve the alternatives through quota-array-dispatch."
+    }
+  ],
+  "default": [
+    { "harness": "codex", "model": "gpt-5.5", "effort": "medium" },
+    { "harness": "pi", "model": "anthropic/claude-sonnet-5", "effort": "medium" }
+  ]
+}

package/assets/reference/docs/examples/process-event-extension/file-signal.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Minimal process-event-adapter/1 example.
+//
+// A source configuration reference has the form file:/absolute/path.
+// source.poll waits until that regular file exists, then returns its bounded
+// UTF-8 contents as external evidence.
+// The result is terminal and classifies as file-signal.
+
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+const MAX_INPUT_BYTES = 65536;
+const MAX_RESULT_BYTES = 16384;
+
+async function readRequest() {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > MAX_INPUT_BYTES) throw new Error("request is oversized");
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function reply(requestId, result) {
+  process.stdout.write(`${JSON.stringify({
+    schema: "firstmate.extension-response.v1",
+    request_id: requestId,
+    ok: true,
+    result,
+    error: null,
+  })}\n`);
+}
+
+function handshake(request) {
+  process.stdout.write(`${JSON.stringify({
+    schema: "firstmate.extension-handshake-response.v1",
+    request_id: request.request_id,
+    extension_id: "org.firstmate.example.file-signal",
+    extension_version: "1.0.0",
+    host_protocol: 1,
+    capability: "process-event-adapter",
+    capability_version: 1,
+    adapter_names: request.capability.adapter_names,
+  })}\n`);
+}
+
+async function waitForFile(reference) {
+  if (typeof reference !== "string" || !reference.startsWith("file:")) {
+    throw new Error("config_ref must have the form file:/absolute/path");
+  }
+  const file = reference.slice("file:".length);
+  if (!path.isAbsolute(file) || path.normalize(file) !== file) {
+    throw new Error("config_ref file path must be normalized and absolute");
+  }
+  const deadline = Date.now() + 55000;
+  while (Date.now() < deadline) {
+    try {
+      const info = await stat(file);
+      if (!info.isFile()) throw new Error("configured path is not a regular file");
+      const bytes = await readFile(file);
+      if (bytes.length === 0 || bytes.length > MAX_RESULT_BYTES) {
+        throw new Error(`configured result must contain 1-${MAX_RESULT_BYTES} bytes`);
+      }
+      const output = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      return output;
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        continue;
+      }
+      throw error;
+    }
+  }
+  return null;
+}
+
+const verb = process.argv[2] || "";
+const request = await readRequest();
+if (verb === "handshake") {
+  handshake(request);
+} else if (verb === "invoke" && request.operation === "source.poll") {
+  const output = await waitForFile(request.input.config_ref);
+  reply(request.request_id, output === null
+    ? { status: "no-result", output: "" }
+    : { status: "result", output });
+} else if (verb === "invoke" && request.operation === "result.classify") {
+  reply(request.request_id, { classification: "file-signal" });
+} else if (verb === "invoke" && request.operation === "result.terminal") {
+  reply(request.request_id, { value: true });
+} else if (verb === "invoke" && request.operation === "result.silent") {
+  reply(request.request_id, { value: false });
+} else {
+  throw new Error("unsupported extension verb or operation");
+}

package/assets/reference/docs/examples/process-event-extension/firstmate-extension.json

@@ -0,0 +1,15 @@
+{
+  "schema": "firstmate.extension-manifest.v1",
+  "id": "org.firstmate.example.file-signal",
+  "version": "1.0.0",
+  "host_protocols": [1],
+  "entrypoint": "file-signal.mjs",
+  "capabilities": [
+    {
+      "name": "process-event-adapter",
+      "versions": [1],
+      "adapter_names": ["file-signal"]
+    }
+  ],
+  "required_consents": ["artifact-references"]
+}

package/assets/reference/docs/examples/watched-tools.json

@@ -0,0 +1,24 @@
+{
+  "tools": [
+    {
+      "name": "firstmate",
+      "git": { "repo": "/absolute/path/to/firstmate", "remote": "origin" }
+    },
+    {
+      "name": "agents-on-the-go",
+      "git": { "repo": "/absolute/path/to/agents-on-the-go", "remote": "origin", "branch": "mainline" }
+    },
+    {
+      "name": "herdr",
+      "command": "herdr",
+      "version_args": ["--version"]
+    },
+    {
+      "name": "no-mistakes",
+      "command": "no-mistakes",
+      "version_args": ["--version"],
+      "announce_args": ["--help"],
+      "announce_pattern": "A new version of no-mistakes is available: [^ ]+ -> [^ ]+"
+    }
+  ]
+}

package/assets/reference/docs/examples/wedge-alarm

@@ -0,0 +1,22 @@
+# config/wedge-alarm - active alert channels for the away-mode injection wedge
+# alarm (bin/fm-supervise-daemon.sh's inject_wedge_alarm). Copy this into a
+# local, gitignored config/wedge-alarm and edit. One channel directive per
+# non-empty, non-comment line; every listed non-off channel fires, best-effort.
+#
+# Directives:
+#   off              position-independent kill switch: disable every active
+#                    alert (the durable marker and tmux status-line flash remain)
+#   auto | default   platform default: macOS -> osascript; other platforms have
+#                    no built-in OS channel (configure a command: line instead)
+#   osascript        macOS Notification Center banner (backend-independent)
+#   herdr            herdr UI notification (herdr notification show)
+#   command:<cmd>    run <cmd> via `sh -c`; the alarm summary is passed as $1 and
+#                    on stdin, so it can reach a phone/pager while you are away
+#
+# An ABSENT config/wedge-alarm behaves as `auto` (default-on on macOS): the
+# alarm exists precisely so a wedged away-mode primary is never silent.
+#
+# Example: a macOS banner plus a push to a phone via ntfy.sh, so a wedge that
+# happens overnight reaches you even away from the machine.
+osascript
+command: curl -fsS -H "Title: firstmate wedge alarm" -d "$1" https://ntfy.sh/replace-with-your-topic