somnus: schema: "somnus://metadata/core/2.0.0" id: "urn:somnus:artifact:01a19a69-87b3-76bf-bbae-83b732aa9e46" revision: 7 title: "somnus-frontmatter" classification: category: "context" type: "index" role: "informative" scope: "component" tags: [] lifecycle: status: "draft" authority: standing: "candidate" scopes: - target_ref: "urn:somnus:artifact:01a19a69-87b3-76bf-bbae-83b732aa9e46" aspects: ["content"] time: updated_at: "2026-11-18T01:01:28+00:00" names: slug: "somnus-metadata-plugin" knowledge: coverage: "artifact" subjects: ["urn:somnus:artifact:01a19a69-87b3-76bf-bbae-83b732aa9e46"] access: visibility: "internal" allowed_uses: ["archive", "search", "reason"] ingestion: disposition: "candidate" body_role: "narrative"
somnus-frontmatter
Host-agnostic Agent Plugin and Agent Skills for Somnus
Frontmatter — a local-first registry that gives every managed file one somnus: block
(frontmatter in Markdown, a comment envelope in code and config, a metadata.somnus member
in notebooks, or a <file>.somnus.yaml sidecar for formats with no carrier), backed by one
global SQLite database ($SOMNUS_HOME/somnus.db) with identity, revisions, relations,
claims, conflicts and full-text search.
Somnus Frontmatter is the agent-facing distribution of that system. The Python package
(somnus-metadata on PyPI; commands somnus and somnus-metadata) owns all behavior.
This npm package distributes two skills and the plugin manifest that expose it — it holds
no metadata logic of its own.
What installs where
somnus-frontmatter install writes exactly two things, and touches no agent's config
files:
| Destination | Contents | Consumers |
|---|---|---|
~/.agents/skills/somnus-frontmatter/ | the everyday operating skill: search, adopt, revise, validate | every Agent Skills client (OpenCode, Codex, Droid, Cursor, …) |
~/.agents/skills/somnus-frontmatter-maintain/ | the substrate skill: watcher/daemon, roots, conflicts, E_HOST, backups, upgrades | agents asked to maintain the system |
~/.agents/plugins/somnus-frontmatter/ | the Agent Plugin: plugin.json + mcp.json + skills/ | Agent Plugins clients; any client loading a plugin by path |
~/.agents/plugins/marketplace.json | one somnus-frontmatter entry upserted (backup kept; foreign entries preserved; an unparseable file is refused, never rewritten) | local plugin marketplaces |
Hosts without Agent Plugins support need their own MCP registration; install prints the
generic entry (somnus --actor somnus-frontmatter mcp, stdio) to adapt. The installer
never rewrites host configs in this version.
Requirements
- Node.js ≥ 18.17 for the installer.
somnus≥ 2.1.0 on PATH (2.1.1+ for full unmanaged-file discovery; 2.2.0+ for the 24/7 watcher and daemon). Install it withpip install -U somnus-metadatain a venv, oruv tool install somnus-metadata/pipx install somnus-metadata.
Install
npm i -g somnus-frontmatter # installs the `somnus-frontmatter` command
somnus-frontmatter install # skills + plugin into ~/.agents/ (add --watch for the daemon)
somnus-frontmatter doctor # backend, registry, watcher, skill/plugin fidelity, live MCP handshake
somnus-frontmatter uninstall # removes exactly what install added; backend and registry stay
--agents-dir DIR redirects the install root (default SOMNUS_FRONTMATTER_AGENTS or
~/.agents). --dry-run prints every action. --force replaces directories the tool did
not create (the originals are moved aside, not deleted). install --install-backend SRC
installs or upgrades the Python backend first (pip, falling back to uv tool, then pipx).
MCP server
Agent Plugins clients launch the server declared in the plugin's mcp.json:
{ "mcpServers": { "somnus-frontmatter": { "type": "stdio", "command": "somnus", "args": ["--actor", "somnus-frontmatter", "mcp"] } } }
One tool per CLI command (q, ls, check, stamp, new, set, status, bump,
index, stale, brief, …); results are the command's text or TSV. Tool results keep
the host's models off raw shell when possible. Non-zero exits set isError with the
diagnostic in the text — read it; it usually names the file, field, and fix.
The two skills
- somnus-frontmatter — using the registry: proactive retrieval before creating documents, adopting files, revision hygiene after edits, validation, lifecycle, and reasoning over the collection graph.
- somnus-frontmatter-maintain — running the substrate: the watcher and
somnus daemon, registered roots andconfig.toml/.somnus.toml, revision and identity conflicts, E_HOST incidents, registry backup/restore, and upgrades.
Safety
- Every install is backed up (
<file>.bak-somnus-frontmatter-<UTC stamp>) before a changed file is rewritten; unchanged files are not rewritten. - Directories this tool wrote carry a
.somnus-frontmatter.jsonmarker (plugin, version, content hash, install time). Install refuses to replace, and uninstall leaves, any directory without it (--forcedeliberately overrides, moving the old one aside). doctorcompares the installed skills and plugin against the packaged bytes and runs a live MCP handshake; drift is aFAIL, not a warning you can miss.- The daemon and the registry are never started, stopped, or reconfigured by
installunless you pass--watch(which only runssomnus daemon install).
Upgrading from plugin 1.x (somnus-metadata-plugin)
The 1.x layout (per-host direct adapters, native Codex/Factory marketplaces,
somnus-metadata MCP entries) is gone. The rename does not touch the backend, the
registry, or any managed file: somnus: blocks and URNs are unchanged.
npm i -g somnus-frontmatter && somnus-frontmatter install— places the new skills and plugin. Re-runningdoctorverifies them.- If a stale
somnus-metadataskill copy remains under~/.agents/skills/or your host's skills directory, remove it; leaving it costs context tokens, not correctness. - Host MCP entries named
somnus-metadatakeep working (the backend is unchanged) but are redundant with the plugin'ssomnus-frontmatterserver. Remove them when convenient, or leave them; both serve the same backend. - Native Codex/Factory plugin registrations from 1.x are orphaned by the rename; use the hosts' own remove/uninstall once. The Python backend is untouched throughout.
Develop
npm test # node --test; fake backend, temporary agents home
npm pack --dry-run
Layout: skills/ (the two Agent Skills), plugin.json + mcp.json (the Agent Plugin
manifest), bin/ + lib/ (the installer and doctor), test/ (unit + conformance tests
against the agent-plugins.org 1.0.0 schema surface). Design decisions, verification
evidence, and release history live with the backend repository (somnus-metadata) in
PLAN.md, DECISIONS.md, and HANDOFF.md.
License
UNLICENSED — all rights reserved. See the backend repository for the project's terms.