@neurodock/cli 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @neurodock/cli changelog
 
+## 0.7.2
+
+### Fixed — `npx @neurodock/cli install-all` failed on `init` with "Could not locate template: profile.example.yaml"
+
+The 0.7.x tarball only shipped `dist/`, but `init`, `validate`, and
+`plugin validate` all resolved their templates and JSON schemas through
+relative paths into the workspace `packages/core/schemas/` folder. That
+folder is not part of the cli tarball, so every fresh `npx` install
+failed the moment `install-all` finished wiring the MCP servers and
+tried to scaffold a profile.
+
+Fix: `scripts/copy-assets.mjs` now also copies `packages/core/schemas/`
+into `dist/assets/schemas/` at build time, and the three resolvers
+(`commands/init.ts`, `profile/validator.ts`, `lib/plugin-schema.ts`)
+check that bundled location first before falling back to the workspace
+candidates used during local development. No behaviour change in the
+monorepo; published tarball now contains the schemas required by every
+first-run code path.
+
 ## 0.7.1
 
 ### Fixed — Windows: daemon autostart no longer flashes a black console window

package/dist/assets/hooks/neurodock_daemon.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 NeuroDock contributors.
 """NeuroDock proactive-guardrail daemon (Phase 3).
 
 A long-running poller that watches the same state files the Phase 1

package/dist/assets/hooks/proactive_guardrail.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 NeuroDock contributors.
 """NeuroDock proactive guardrail — Claude Code hook (self-contained).
 
 Bundled with `@neurodock/cli`; copied to `~/.neurodock/hooks/` by

package/dist/assets/hooks/test_daemon_escape.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 NeuroDock contributors.
 """Tests for the M5 notification-text escape functions in neurodock_daemon.py.
 
 Security regression test: verify that shell-injection characters in title/

package/dist/assets/schemas/plugin.example.yaml

@@ -0,0 +1,193 @@
+# ==============================================================================
+# WELCOME — THIS IS A WORKED EXAMPLE OF A PLUGIN MANIFEST
+# ==============================================================================
+# Plugins are how NeuroDock grows without us having to change the core. This
+# file shows every field you can put in your own plugin's "plugin.yaml" file.
+#
+# You don't need to use every field. Most of them are optional. Copy this
+# file as a starting point and delete anything you don't need.
+#
+# WHERE THE CONTRACT LIVES (for the curious):
+#   packages/core/schemas/plugin.schema.json     — the machine-checkable rules
+#   docs/decisions/0007-plugin-protocol.md       — the "why" behind the rules
+#
+# HOW PLUGINS GET FOUND:
+#   When NeuroDock starts, it looks in two places for plugins:
+#     1. plugins/<your-plugin>/plugin.yaml   (lives inside this repo)
+#     2. ~/.local/share/neurodock/plugins/<your-plugin>/plugin.yaml
+#        (lives on your own computer, just for you)
+#   No central server. No sign-up. No registry to publish to.
+#
+# WILL UPGRADING BREAK MY PLUGIN?
+#   No. If we add new fields in a future version, older versions of NeuroDock
+#   will leave them alone instead of stripping them out. You can edit your
+#   plugin on a new install, swap back to an old one, and not lose anything.
+# ==============================================================================
+
+# Leave this as "0.1.0". It just tells NeuroDock which version of the plugin
+# format you're using. If you're newer than NeuroDock, you'll get a warning,
+# not an error.
+schema_version: "0.1.0"
+
+# ------------------------------------------------------------------------------
+# 1. WHO THIS PLUGIN IS (Required)
+# ------------------------------------------------------------------------------
+# A short, unique name. Lowercase, dashes between words.
+# Tip: starting it with your handle (e.g. "org-eobrien-...") helps avoid
+# clashes with other contributors' plugins. Not required.
+name: "ie-corporate-translation"
+
+# What kind of plugin is this? Pick one:
+#   skill              — adds a Claude skill (a markdown file with triggers)
+#   mcp-server         — adds a new MCP server with new tools
+#   profile            — adds a profile preset users can copy
+#   translation-pack   — adds translation prompts for a domain (legal, sales...)
+#   language-pack      — adds prompts for a non-US-English workplace culture
+#   theme              — adds a visual theme for UI surfaces
+type: "language-pack"
+
+# Your plugin's version number. Use semver (e.g. "0.2.1"). Bumping the
+# patch (third) number means "small fix, nothing broke". Bumping the minor
+# (middle) means "added a new feature, nothing broke". Bumping the major
+# (first) means "I changed something that might break people". Try not to
+# bump the major in 0.1.x unless you really have to.
+version: "0.2.1"
+
+# A one-sentence description of what this plugin does. This is what people
+# see in plugin listings. Don't make clinical claims here — say what the
+# plugin DOES, not what it TREATS.
+description: "Hiberno-English to neutral corporate English for ND professionals — direct decoding of indirect Irish workplace register without flattening voice."
+
+# ------------------------------------------------------------------------------
+# 2. WHO MADE IT (Optional but appreciated)
+# ------------------------------------------------------------------------------
+# Listing at least one maintainer helps when something needs fixing.
+# "role" is whatever makes sense — maintainer, reviewer, lived-experience reviewer.
+authors:
+  - name: "Eoin O'Brien"
+    handle: "@eobrien"
+    role: "maintainer"
+  - name: "Síofra Ní Bhriain"
+    handle: "@sionb"
+    role: "reviewer" # lived-experience reviewer
+
+# ------------------------------------------------------------------------------
+# 3. WHO IS THIS PLUGIN FOR? (Optional)
+# ------------------------------------------------------------------------------
+# Which neurotypes does this plugin help? Leave the list empty (or remove
+# this block) if it works for everyone — most plugins do.
+#
+# If a user's profile lists any of these neurotypes, NeuroDock turns this
+# plugin on for them automatically. If not, they can still turn it on by
+# hand — your plugin isn't blocked, just not on by default.
+neurotypes:
+  - "adhd"
+  - "audhd"
+  - "asd"
+
+# Which spoken-language / workplace cultures is this plugin for?
+# REQUIRED if type is "language-pack" or "translation-pack".
+# Use BCP 47 tags ("en-IE" = Irish English, "ja-JP" = Japanese, etc.)
+locale:
+  - "en-IE"
+  - "en-GB" # Irish-English register often shows up in UK workplaces too
+
+# ------------------------------------------------------------------------------
+# 4. WHAT THIS PLUGIN NEEDS TO RUN (Optional)
+# ------------------------------------------------------------------------------
+# If your plugin needs a specific version of NeuroDock or another MCP server,
+# say so here. NeuroDock will skip loading your plugin (cleanly) if any of
+# these aren't around.
+requires:
+  substrate_version: ">=0.1.0"
+  mcp_servers:
+    - name: "mcp-translation"
+      version: ">=0.1.0"
+  skills: []
+  plugins: []
+
+# ------------------------------------------------------------------------------
+# 5. WHAT YOUR PLUGIN PROVIDES
+# ------------------------------------------------------------------------------
+# This is the actual content your plugin ships. Each entry points at a file
+# inside your plugin's directory. All paths are relative — your plugin can't
+# reach outside its own folder. That's a deliberate safety rule.
+provides:
+  - type: "language-prompt-override"
+    id: "translate-incoming-en-ie"
+    path: "./prompts/translate-incoming.md"
+    # You can narrow when a single file applies, separate from the
+    # whole-plugin neurotypes/locale settings above.
+    applies_to:
+      locale: ["en-IE", "en-GB"]
+
+  - type: "language-prompt-override"
+    id: "check-tone-en-ie"
+    path: "./prompts/check-tone.md"
+
+  - type: "language-prompt-override"
+    id: "brief-meeting-en-ie"
+    path: "./prompts/brief-meeting.md"
+
+  - type: "translation-prompt"
+    id: "decode-grand"
+    path: "./prompts/idioms/decode-grand.md"
+    # "Grand" in Hiberno-English can mean anything from "excellent" to
+    # "this is not fine and we are not going to discuss it further." It
+    # earns its own prompt.
+
+# ------------------------------------------------------------------------------
+# 6. WHERE THIS PLUGIN CAME FROM (Required)
+# ------------------------------------------------------------------------------
+# This is the "trust" block. It tells NeuroDock how much social process has
+# touched this plugin so it knows whether to prompt the user before activating.
+#
+# Levels:
+#   official     — published by the NeuroDock maintainer; installs silently
+#   verified     — signed against the maintainer keyring; installs silently
+#   community    — your own plugin, author-signed; user gets a one-time prompt
+#   experimental — unsigned; NeuroDock refuses by default unless user opts in
+#
+# Most contributor plugins are "community". That's a good thing.
+trust:
+  level: "community"
+  signature: |
+    -----BEGIN PGP SIGNATURE-----
+    (detached signature over sha256(plugin.yaml + provides[].path contents))
+    -----END PGP SIGNATURE-----
+  keyring_fingerprint: "A1B2 C3D4 E5F6 7890 1234 5678 9ABC DEF0 1234 5678"
+  source_url: "https://github.com/eobrien/ie-corporate-translation"
+
+# ------------------------------------------------------------------------------
+# 7. LICENSE (Required)
+# ------------------------------------------------------------------------------
+# Your plugin's licence. Must be one of the allowed-list licences (they all
+# play nicely with AGPL-3.0). If you pick one that isn't on the list,
+# NeuroDock will refuse to load the plugin with a clear "license_not_allowed"
+# error so nothing silently fails.
+license: "AGPL-3.0-or-later"
+
+# ------------------------------------------------------------------------------
+# 8. WHERE PEOPLE CAN LEARN MORE (Optional)
+# ------------------------------------------------------------------------------
+homepage: "https://hiberno-translate.example.org"
+repository: "https://github.com/eobrien/ie-corporate-translation"
+keywords:
+  - "translation"
+  - "hiberno-english"
+  - "corporate"
+  - "indirect-speech"
+
+# ------------------------------------------------------------------------------
+# 9. LIFECYCLE HOOKS (Optional, advanced)
+# ------------------------------------------------------------------------------
+# Scripts that run on install/uninstall. For safety, NeuroDock will only
+# run these for "official" or "verified" plugins right now. You can declare
+# them for a community plugin — they'll just sit there politely ignored
+# until the safer hook sandbox lands.
+hooks:
+  on_install: "./install.sh" # idempotent; no network, no writing outside the plugin dir
+  on_uninstall: "./uninstall.sh" # clean up anything you created locally
+
+# Reserved for future use. Leave empty.
+compatibility: {}

package/dist/assets/schemas/plugin.minimal.yaml

@@ -0,0 +1,30 @@
+# ==============================================================================
+# THE SMALLEST POSSIBLE PLUGIN MANIFEST
+# ==============================================================================
+# This file contains ONLY the required fields for a NeuroDock plugin. Every
+# other field is optional. If you're just starting out, this is the shape to
+# copy.
+#
+# For the full version with every option explained, see:
+#   packages/core/schemas/plugin.example.yaml
+#
+# For the design rationale behind why these fields exist:
+#   docs/decisions/0007-plugin-protocol.md
+#
+# The "neurodock plugin scaffold" command would write something close to
+# this file. Every required field is present, no optional ones are.
+# ==============================================================================
+
+schema_version: "0.1.0"
+name: "minimal-example"
+type: "skill"
+version: "0.1.0"
+description: "Minimal valid plugin manifest — replace with your one-sentence summary."
+license: "AGPL-3.0-or-later"
+trust:
+  level: "experimental"
+  # Heads up: with trust.level = "experimental" NeuroDock will refuse to
+  # load this plugin by default — that's a safety feature, not a bug.
+  # To get it loading, do one of:
+  #   (a) bump trust.level to "community" and add a "source_url", or
+  #   (b) opt in just this once: `neurodock plugin trust <name> --once`

package/dist/assets/schemas/plugin.schema.json

@@ -0,0 +1,391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.neurodock.org/plugin/v0.1.0/plugin.schema.json",
+  "title": "NeuroDock Plugin Manifest",
+  "description": "Manifest contract for every plugin discovered under plugins/<name>/plugin.yaml or ~/.neurodock/plugins/<name>/plugin.yaml. Declares plugin type, version, neurotype targeting, dependencies, provided assets, trust level, license, and lifecycle hooks. Forward-compatible: unknown keys at every nesting level MUST be preserved by loaders.",
+  "$comment": "Discovery is filesystem-based in v0.1.0: the substrate walks plugins/*/plugin.yaml (in-repo) and $XDG_DATA_HOME/neurodock/plugins/*/plugin.yaml (per-user) at init. The Phase 3 federated registry at plugins.neurodock.org is opt-in and indexes signed manifests; the protocol does NOT depend on a central registry. Loaders MUST preserve unknown top-level and nested keys when round-tripping a manifest so a v0.1.0 install can read and re-emit a v0.2.0 manifest without data loss. Asset paths in `provides[].path` and `hooks.*` are sandboxed: the resolved absolute path MUST remain inside the plugin's directory after normalisation. Symlinks pointing outside the plugin dir MUST be rejected by the loader.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "name",
+    "type",
+    "version",
+    "description",
+    "license",
+    "trust"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Required. Plugin manifest schema version this file targets. Loaders SHOULD warn but never fail when the version is newer than what they understand; they MUST still load known fields and preserve unknown ones. Use the same semver shape as the profile schema.",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "examples": ["0.1.0"]
+    },
+    "name": {
+      "type": "string",
+      "description": "Required. Globally unique within the plugin's `type`. Kebab-case, ASCII lowercase, digits, and hyphens. MUST start with a letter. Reverse-DNS prefixes (e.g. 'org-eobrien-') are RECOMMENDED for community plugins to avoid collisions; not enforced in v0.1.0 to keep contribution friction low.",
+      "pattern": "^[a-z][a-z0-9-]{1,62}[a-z0-9]$",
+      "minLength": 3,
+      "maxLength": 64,
+      "examples": ["ie-corporate-translation", "adhd-pomodoro", "mcp-calendar"]
+    },
+    "type": {
+      "type": "string",
+      "description": "Required. Plugin type. Six values in v0.1.0. New types are an ADDITIVE forward-compat change (no major bump); v0.1.0 loaders encountering an unknown type MUST skip the plugin with a structured 'unknown_plugin_type' warning rather than erroring.",
+      "enum": [
+        "skill",
+        "mcp-server",
+        "profile",
+        "translation-pack",
+        "language-pack",
+        "theme"
+      ],
+      "examples": ["language-pack", "skill"]
+    },
+    "version": {
+      "type": "string",
+      "description": "Required. Plugin version. Strict semver (no pre-release qualifiers in v0.1.0). Patch and minor bumps within v0.1.x MUST be additive-only; renames, removals, and required-field additions are major bumps.",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "examples": ["0.2.1", "1.0.0"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Required. One-sentence human description shown in plugin listings. Must not make clinical claims (per ETHICS commitment 1).",
+      "minLength": 10,
+      "maxLength": 280,
+      "examples": [
+        "Hiberno-English to neutral corporate English translation prompts for ND professionals."
+      ]
+    },
+    "authors": {
+      "type": "array",
+      "description": "Optional. Plugin authors. At least one entry with role 'maintainer' is RECOMMENDED for community plugins so the substrate can surface a contact in trust prompts. Empty / absent is acceptable for in-repo first-party plugins authored by the maintainer.",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120,
+            "description": "Display name or handle."
+          },
+          "handle": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Optional. GitHub-style '@handle' (or other platform-prefixed handle).",
+            "examples": ["@eobrien"]
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Optional. Contact email. Plugins published through the federated registry MAY omit this; in-repo plugins SHOULD omit it (use the GitHub handle instead). Never required."
+          },
+          "role": {
+            "type": "string",
+            "enum": ["maintainer", "contributor", "reviewer"],
+            "default": "contributor",
+            "description": "Role in this plugin's authorship. 'maintainer' = accepts issues, signs releases; 'contributor' = wrote part of it; 'reviewer' = clinical or  who signed off."
+          }
+        }
+      }
+    },
+    "neurotypes": {
+      "type": "array",
+      "description": "Subset of the values allowed by profile.identity.neurotypes that this plugin targets. The substrate auto-activates a plugin only when this array intersects the user's profile.identity.neurotypes (non-empty intersection). Empty array (the default when omitted) means the plugin is neurotype-agnostic and auto-activates for every user.",
+      "minItems": 0,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "adhd",
+          "asd",
+          "audhd",
+          "ocd",
+          "dyslexia",
+          "dyspraxia",
+          "tourette",
+          "other"
+        ]
+      },
+      "default": [],
+      "examples": [["adhd"], ["adhd", "audhd"], []]
+    },
+    "locale": {
+      "type": "array",
+      "description": "BCP 47 locale tags this plugin targets. REQUIRED for type 'language-pack' and 'translation-pack' (loader rejects manifest when empty for those types); ignored for other types. Substrate prefers locale-matched plugins over locale-agnostic ones when both apply.",
+      "minItems": 0,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z]{2,4})*(-[a-zA-Z0-9]{1,8})*$"
+      },
+      "examples": [["en-IE", "en-GB"], ["ja-JP"], ["de-DE"]]
+    },
+    "requires": {
+      "type": "object",
+      "description": "Optional. Hard runtime requirements. The substrate refuses to activate the plugin when any requirement is unmet; refusal is loud (structured warning + log entry) rather than silent. Circular requirement chains (A requires B requires A) MUST be detected at load time and reported via the 'plugin_requirement_cycle' error.",
+      "additionalProperties": true,
+      "properties": {
+        "substrate_version": {
+          "type": "string",
+          "description": "Required substrate (`@neurodock/core`) version range. Standard semver-range syntax (`>=`, `<`, `~`, `^`, `||`). Defaults to '>=0.1.0' when omitted.",
+          "examples": [">=0.1.0", ">=0.1.0 <0.3.0"]
+        },
+        "mcp_servers": {
+          "type": "array",
+          "description": "MCP servers the plugin's assets call into. Each entry is matched against the substrate's installed-server registry by name; the version range is matched against the server's package version.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "MCP server name as published, e.g. 'mcp-translation'.",
+                "examples": ["mcp-translation", "mcp-cognitive-graph"]
+              },
+              "version": {
+                "type": "string",
+                "description": "Semver range. Defaults to '>=0.1.0' when omitted.",
+                "examples": [">=0.1.0"]
+              }
+            }
+          }
+        },
+        "skills": {
+          "type": "array",
+          "description": "Other skills this plugin depends on at runtime (by skill name as declared in the depended-on skill's SKILL.md frontmatter or plugin.yaml `name`).",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "examples": ["adhd-daily-planner"]
+              },
+              "version": {
+                "type": "string",
+                "examples": [">=0.1.0"]
+              }
+            }
+          }
+        },
+        "plugins": {
+          "type": "array",
+          "description": "Other plugins this plugin depends on. By `name` (and optional `type` disambiguator when the name is reused across types). Circular `requires.plugins` chains are rejected at load.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "skill",
+                  "mcp-server",
+                  "profile",
+                  "translation-pack",
+                  "language-pack",
+                  "theme"
+                ]
+              },
+              "version": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "provides": {
+      "type": "array",
+      "description": "Assets this plugin exposes to the substrate. Every entry has an `id` (unique within the manifest), a sub-`type` describing what kind of asset it is, and a `path` relative to the plugin's directory. Paths are sandboxed: after normalisation the resolved absolute path MUST remain inside the plugin's directory; '..' traversal and absolute paths are rejected by the loader.",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["type", "id", "path"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Asset sub-type. The substrate dispatches discovery on this value: 'skill' → registered with the skill loader; 'mcp-server-binary' → registered with the MCP supervisor; 'translation-prompt' → registered with mcp-translation's prompt library; 'language-prompt-override' → shadows the matching default prompt for the manifest's `locale`; 'profile-preset' → exposed under `profiles/presets/`; 'theme-bundle' → registered with the design system. Unknown values are preserved on round-trip but skipped by the registrar with a structured 'unknown_asset_type' warning.",
+            "enum": [
+              "skill",
+              "mcp-server-binary",
+              "translation-prompt",
+              "language-prompt-override",
+              "profile-preset",
+              "theme-bundle"
+            ]
+          },
+          "id": {
+            "type": "string",
+            "description": "Identifier unique within this manifest's `provides[]`. Kebab-case. The substrate exposes the asset under '<plugin.name>/<provides.id>'.",
+            "pattern": "^[a-z][a-z0-9-]{0,62}[a-z0-9]$",
+            "examples": ["translate-hiberno-direct", "tone-keigo-customer"]
+          },
+          "path": {
+            "type": "string",
+            "description": "Path to the asset, RELATIVE to the plugin directory. MUST start with './' or a non-leading-slash subdirectory. Loader normalises and rejects any path resolving outside the plugin directory or pointing through a symlink that does so.",
+            "pattern": "^(\\./)?[^/\\\\][^\\\\:*?\"<>|]*$",
+            "examples": [
+              "./prompts/translate-hiberno-direct.md",
+              "prompts/tone-warm.md"
+            ]
+          },
+          "applies_to": {
+            "type": "object",
+            "description": "Optional. Activation predicate for this specific asset, evaluated against the user's profile. Defaults to inheriting the manifest-level `neurotypes` + `locale`. An asset's predicate, when present, overrides the manifest-level intersection for that asset only.",
+            "additionalProperties": true,
+            "properties": {
+              "neurotypes": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string" }
+              },
+              "locale": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "trust": {
+      "type": "object",
+      "description": "Required. Provenance and trust declaration. Four-tier ladder. 'official' (NeuroDock Maintainer-published) and 'verified' (signed by a verified contributor whose key sits in the maintainer-maintained keyring) install without user prompting. 'community' (author-signed; provenance recorded but not vouched) and 'experimental' (unsigned) prompt the user per profile preference. The substrate's default profile setting is 'prompt for community, refuse for experimental'.",
+      "additionalProperties": true,
+      "required": ["level"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["official", "verified", "community", "experimental"],
+          "description": "Trust tier. See trust ladder above."
+        },
+        "signature": {
+          "type": "string",
+          "description": "Optional in v0.1.0; required for 'official' and 'verified' once signature verification ships in Phase 3. ASCII-armored PGP detached signature over sha256(plugin.yaml + concatenation of provides[].path file contents in declaration order). Verification implementation is deferred; v0.1.0 schemas reserve the field and store it on round-trip.",
+          "examples": ["-----BEGIN PGP SIGNATURE----- ..."]
+        },
+        "keyring_fingerprint": {
+          "type": "string",
+          "description": "Optional. PGP fingerprint of the key that produced `signature`. Lets the substrate look the key up in the maintainer keyring (for 'verified') or in a local trust-on-first-use store (for 'community').",
+          "pattern": "^[A-F0-9 ]{40,60}$",
+          "examples": ["A1B2 C3D4 E5F6 7890 1234 5678 9ABC DEF0 1234 5678"]
+        },
+        "source_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Required for 'community' and 'experimental'. URL of the canonical source the user can audit before trusting the plugin (typically the public repository).",
+          "examples": ["https://github.com/eobrien/ie-corporate-translation"]
+        }
+      }
+    },
+    "license": {
+      "type": "string",
+      "description": "Required. SPDX license identifier. v0.1.0 whitelist enforces AGPL-3.0-or-later-compatible licenses ONLY. Plugins with a non-listed license refuse to load and surface a 'license_not_allowed' error. The whitelist is conservative on purpose: the substrate is AGPL-3.0-or-later and plugins are distributed alongside it, so we keep license boundaries clean. The whitelist may be extended in additive minor bumps via ADR.",
+      "enum": [
+        "AGPL-3.0-or-later",
+        "AGPL-3.0-only",
+        "GPL-3.0-or-later",
+        "GPL-3.0-only",
+        "LGPL-3.0-or-later",
+        "MIT",
+        "Apache-2.0",
+        "BSD-3-Clause",
+        "BSD-2-Clause",
+        "ISC",
+        "MPL-2.0",
+        "CC0-1.0"
+      ],
+      "examples": ["AGPL-3.0-or-later", "MIT"]
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Optional. Public homepage for the plugin (project page, docs site, etc.)."
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "Optional. Source-code repository. RECOMMENDED for any plugin with trust level 'community' or 'experimental' so users can audit the source."
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Optional. Discovery keywords. Federated registry surfaces these in search.",
+      "items": { "type": "string", "maxLength": 32 },
+      "maxItems": 16,
+      "examples": [["translation", "hiberno-english", "corporate"]]
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Optional. Lifecycle hooks. Constrained: hooks may invoke ONLY shell scripts shipped inside the plugin directory, and those scripts run under an allow-list of operations (read-only filesystem access inside the plugin dir; no network; no writes outside the plugin dir; no privilege escalation; no fork/exec of unallowed binaries). The substrate's hook executor enforces the sandbox; manifests that declare hooks but whose scripts violate the allow-list at runtime have their hooks aborted and a structured 'hook_sandbox_violation' error logged. v0.1.0 ships with an executor that simply REFUSES to run hooks unless trust.level in {'official', 'verified'}; community plugins MAY declare hooks but they will be ignored until the sandbox lands in Phase 3.",
+      "additionalProperties": true,
+      "properties": {
+        "on_install": {
+          "type": "string",
+          "description": "Path (relative to plugin directory) to a shell script run once after plugin discovery. Same sandboxing as `provides[].path`. Idempotent: the substrate may re-run on_install if the previous run failed or if the plugin version changed.",
+          "pattern": "^(\\./)?[^/\\\\][^\\\\:*?\"<>|]*$",
+          "examples": ["./install.sh"]
+        },
+        "on_uninstall": {
+          "type": "string",
+          "description": "Path to a shell script run before plugin removal. Same sandboxing as `on_install`. The substrate runs the hook even when the user is uninstalling because a previous install failed.",
+          "pattern": "^(\\./)?[^/\\\\][^\\\\:*?\"<>|]*$"
+        }
+      }
+    },
+    "compatibility": {
+      "type": "object",
+      "description": "Optional. Forward-compatibility declarations. Reserved for future use; v0.1.0 loaders ignore unknown sub-keys but preserve them on round-trip.",
+      "additionalProperties": true
+    }
+  },
+  "examples": [
+    {
+      "schema_version": "0.1.0",
+      "name": "ie-corporate-translation",
+      "type": "language-pack",
+      "version": "0.2.1",
+      "description": "Hiberno-English to neutral corporate English translation prompts for ND professionals.",
+      "authors": [
+        { "name": "Eoin O'Brien", "handle": "@eobrien", "role": "maintainer" }
+      ],
+      "neurotypes": ["adhd", "audhd", "asd"],
+      "locale": ["en-IE", "en-GB"],
+      "requires": {
+        "substrate_version": ">=0.1.0",
+        "mcp_servers": [{ "name": "mcp-translation", "version": ">=0.1.0" }]
+      },
+      "provides": [
+        {
+          "type": "language-prompt-override",
+          "id": "translate-incoming-en-ie",
+          "path": "./prompts/translate-incoming.md"
+        }
+      ],
+      "trust": {
+        "level": "community",
+        "source_url": "https://github.com/eobrien/ie-corporate-translation"
+      },
+      "license": "AGPL-3.0-or-later",
+      "repository": "https://github.com/eobrien/ie-corporate-translation",
+      "keywords": ["translation", "hiberno-english", "corporate"]
+    },
+    {
+      "schema_version": "0.1.0",
+      "name": "minimal-example",
+      "type": "skill",
+      "version": "0.1.0",
+      "description": "Minimal valid plugin manifest example.",
+      "trust": { "level": "official" },
+      "license": "AGPL-3.0-or-later"
+    }
+  ]
+}