{"_id":"@autoworks-ai/autovault","_rev":"3-6626d7ad62e5ebaaca481e8ec43014f0","name":"@autoworks-ai/autovault","dist-tags":{"latest":"0.5.0"},"versions":{"0.3.0":{"name":"@autoworks-ai/autovault","version":"0.3.0","keywords":["mcp","model-context-protocol","claude","claude-code","cursor","codex","skills","agent","autovault"],"license":"MIT","_id":"@autoworks-ai/autovault@0.3.0","maintainers":[{"name":"jgarturo","email":"info@verygoodplugins.com"}],"homepage":"https://github.com/autoworks-ai/autovault#readme","bugs":{"url":"https://github.com/autoworks-ai/autovault/issues"},"bin":{"autovault":"dist/cli.js"},"dist":{"shasum":"78f123c2ac6de5a27cd390600b31184cc9068106","tarball":"https://registry.npmjs.org/@autoworks-ai/autovault/-/autovault-0.3.0.tgz","fileCount":83,"integrity":"sha512-rNOAcjGIqfEYHhp1UaaZeobicaaTHjlIZwhH75DRLeNOnAAsT/yy9OcFEB0sy52M9AmE/ZaVUt69QLW/MhJLrQ==","signatures":[{"sig":"MEUCIGGUfHBY7J1UJwKBlSDDcFeWe0+JZQfpKTaqjIAOiAMlAiEA/7W3v8Ms+uisGzlHJSAlKGafje8EYMD5AtfpAKhKdhI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":594034},"main":"dist/library.js","type":"module","engines":{"node":">=24.0.0"},"exports":{".":"./dist/library.js","./cli":"./dist/cli.js","./mcp":"./dist/index.js","./remote":"./dist/remote.js"},"mcpName":"io.github.autoworks-ai/autovault","scripts":{"dev":"tsx watch src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","prepare":"npm run build","test:watch":"vitest","start:stdio":"node dist/index.js","smoke:remote":"node scripts/remote-smoke.mjs","start:remote":"node dist/remote.js","sync:profiles":"tsx src/cli.ts sync-profiles","import:autohub":"tsx src/cli.ts import-autohub --tool-filters ../autohub/config/tool-filters.json --mcp-servers ../autohub/config/mcp-servers.json --reset","prepublishOnly":"npm test"},"_npmUser":{"name":"jgarturo","email":"info@verygoodplugins.com"},"repository":{"url":"git+https://github.com/autoworks-ai/autovault.git","type":"git"},"_npmVersion":"11.12.1","description":"AutoVault local capability library and MCP compatibility server","directories":{},"_nodeVersion":"24.15.0","dependencies":{"zod":"^4.4.3","dotenv":"^17.4.2","express":"^5.2.1","tweetnacl":"^1.0.3","minisearch":"^7.1.1","gray-matter":"^4.0.3","@clack/prompts":"^1.4.0","better-sqlite3":"^12.10.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.1","vitest":"^4.1.6","typescript":"^6.0.3","@types/node":"^24.12.4","@types/express":"^5.0.6","@vitest/coverage-v8":"^4.1.6","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/autovault_0.3.0_1778733404432_0.05556189959731528","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@autoworks-ai/autovault","version":"0.4.0","keywords":["mcp","model-context-protocol","claude","claude-code","cursor","codex","skills","agent","autovault"],"license":"MIT","_id":"@autoworks-ai/autovault@0.4.0","maintainers":[{"name":"jgarturo","email":"info@verygoodplugins.com"}],"homepage":"https://github.com/autoworks-ai/autovault#readme","bugs":{"url":"https://github.com/autoworks-ai/autovault/issues"},"bin":{"autovault":"dist/cli.js"},"dist":{"shasum":"e5d65b03887f41339c6e381406ee3733d688385c","tarball":"https://registry.npmjs.org/@autoworks-ai/autovault/-/autovault-0.4.0.tgz","fileCount":85,"integrity":"sha512-xW37Az7I9aNfQBKCE0H77eJXp5gs4Hu+37+YigEP88kL07G/NMr36i/QAqUIW3B5ZZAzBQQmylcElwzIB+OPXA==","signatures":[{"sig":"MEYCIQCrzSnst2aDdssyhyjMEe4cztxjWRyHTXon+QnlGXCFmgIhANNgyfOh7ED2fCA31KQ9tahbbVcKrrELpibNsfqPAwWT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@autoworks-ai%2fautovault@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":637688},"main":"dist/library.js","type":"module","engines":{"node":">=22.0.0"},"exports":{".":"./dist/library.js","./cli":"./dist/cli.js","./mcp":"./dist/index.js","./remote":"./dist/remote.js"},"gitHead":"493153f8bc0a7c8bee0f641b56ac98113cf07566","mcpName":"io.github.autoworks-ai/autovault","scripts":{"dev":"tsx watch src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","prepare":"npm run build","test:watch":"vitest","start:stdio":"node dist/index.js","smoke:remote":"node scripts/remote-smoke.mjs","start:remote":"node dist/remote.js","sync:profiles":"tsx src/cli.ts sync-profiles","import:autohub":"tsx src/cli.ts import-autohub --tool-filters ../autohub/config/tool-filters.json --mcp-servers ../autohub/config/mcp-servers.json --reset","prepublishOnly":"npm test"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ba481e30-b497-403b-9ceb-aad024278c7d"}},"repository":{"url":"git+https://github.com/autoworks-ai/autovault.git","type":"git"},"_npmVersion":"11.12.1","description":"AutoVault local capability library and MCP compatibility server","directories":{},"_nodeVersion":"24.15.0","dependencies":{"zod":"^4.4.3","dotenv":"^17.4.2","express":"^5.2.1","tweetnacl":"^1.0.3","minisearch":"^7.1.1","gray-matter":"^4.0.3","@clack/prompts":"^1.4.0","better-sqlite3":"^12.10.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.1","vitest":"^4.1.6","typescript":"^6.0.3","@types/node":"^22.19.19","@types/express":"^5.0.6","@vitest/coverage-v8":"^4.1.6","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/autovault_0.4.0_1779453494710_0.5321002627318592","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"_id":"@autoworks-ai/autovault@0.5.0","bin":{"autovault":"dist/cli.js"},"bugs":{"url":"https://github.com/autoworks-ai/autovault/issues"},"dist":{"shasum":"a343cdfa7122ca76da0b0d951864f6a7a6091103","tarball":"https://registry.npmjs.org/@autoworks-ai/autovault/-/autovault-0.5.0.tgz","fileCount":128,"integrity":"sha512-THBJlhFkSGfZVWh50RH3qxhpvM0+XqHTY/SPPCEXQYGuUqHYGPgSLBLhZDI5EebrWRPuqGzKBY6/JCrwTFYk8g==","signatures":[{"sig":"MEQCIGI18qGUaToY35ebGfp52JGP9Iy/F1G1CfAZzBFaCk/FAiBedSn/g2MDEQb3+qzkjAz4XsRFWgwQ4D68hHvVME4bRw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHy9Il0wBkT0NXKRcgUb2r1FAT8/7ZBPMIucz5qx9R/6AiEA7udHk8PZtGKH2NKZoxw1LMD9srR6e00odxRczIRksAU="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@autoworks-ai%2fautovault@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1589285},"main":"dist/library.js","name":"@autoworks-ai/autovault","type":"module","engines":{"node":">=22.0.0"},"exports":{".":"./dist/library.js","./cli":"./dist/cli.js","./mcp":"./dist/index.js","./remote":"./dist/remote.js"},"gitHead":"5c88ac31dcd9ff8fa27846e7cbf2a433eac29e03","license":"MIT","mcpName":"io.github.autoworks-ai/autovault","scripts":{"dev":"tsx watch src/index.ts","test":"vitest run","build":"npm run build:ui && tsc -p tsconfig.json","start":"node dist/index.js","prepare":"npm run build","build:ui":"npm run typecheck:ui && vite build --config ui/client/vite.config.ts","test:watch":"vitest","start:stdio":"node dist/index.js","smoke:remote":"node scripts/remote-smoke.mjs","start:remote":"node dist/remote.js","typecheck:ui":"tsc -p ui/client/tsconfig.json --noEmit","sync:profiles":"tsx src/cli.ts sync-profiles","import:autohub":"tsx src/cli.ts import-autohub --tool-filters ../autohub/config/tool-filters.json --mcp-servers ../autohub/config/mcp-servers.json --reset","prepublishOnly":"npm test"},"version":"0.5.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ba481e30-b497-403b-9ceb-aad024278c7d"}},"homepage":"https://github.com/autoworks-ai/autovault#readme","keywords":["mcp","model-context-protocol","claude","claude-code","cursor","codex","skills","agent","autovault"],"repository":{"url":"git+https://github.com/autoworks-ai/autovault.git","type":"git"},"_npmVersion":"11.17.0","description":"AutoVault local capability library and MCP compatibility server","directories":{},"maintainers":[{"name":"jgarturo","email":"info@verygoodplugins.com"}],"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.4.3","react":"^19.2.6","dotenv":"^17.4.2","express":"^5.2.1","react-dom":"^19.2.6","tweetnacl":"^1.0.3","minisearch":"^7.1.1","gray-matter":"^4.0.3","lucide-react":"^1.17.0","@clack/prompts":"^1.4.0","better-sqlite3":"^12.10.0","@fontsource/inter":"^5.2.8","@modelcontextprotocol/sdk":"^1.12.0","@fontsource/jetbrains-mono":"^5.2.8","@fontsource/instrument-serif":"^5.2.8"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.1","vite":"^8.0.15","vitest":"^4.1.6","typescript":"^6.0.3","@types/node":"^22.19.19","@types/react":"^19.2.15","@types/express":"^5.0.6","@types/react-dom":"^19.2.3","@vitest/coverage-v8":"^4.1.6","@vitejs/plugin-react":"^6.0.2","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/autovault_0.5.0_1787705097069_0.33186878222387284"}}},"time":{"created":"2026-05-14T04:36:44.295Z","modified":"2026-08-26T00:44:57.625Z","0.3.0":"2026-05-14T04:36:44.601Z","0.4.0":"2026-05-22T12:38:14.888Z","0.5.0":"2026-08-26T00:44:57.190Z"},"bugs":{"url":"https://github.com/autoworks-ai/autovault/issues"},"license":"MIT","homepage":"https://github.com/autoworks-ai/autovault#readme","keywords":["mcp","model-context-protocol","claude","claude-code","cursor","codex","skills","agent","autovault"],"repository":{"url":"git+https://github.com/autoworks-ai/autovault.git","type":"git"},"description":"AutoVault local capability library and MCP compatibility server","maintainers":[{"name":"jgarturo","email":"info@verygoodplugins.com"}],"readme":"# AutoVault\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@autoworks-ai/autovault\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/%40autoworks-ai%2Fautovault?color=cb3837\"></a>\n  <a href=\"https://www.npmjs.com/package/@autoworks-ai/autovault\"><img alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/%40autoworks-ai%2Fautovault?color=cb3837\"></a>\n  <a href=\"https://github.com/autoworks-ai/homebrew-tap/blob/main/Formula/autovault.rb\"><img alt=\"Homebrew tap\" src=\"https://img.shields.io/badge/homebrew-autoworks--ai%2Ftap%2Fautovault-FBB040?logo=homebrew\"></a>\n  <a href=\"https://github.com/autoworks-ai/autovault/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/autoworks-ai/autovault/actions/workflows/ci.yml/badge.svg\"></a>\n  <a href=\"https://github.com/autoworks-ai/autovault/actions/workflows/security.yml\"><img alt=\"Security\" src=\"https://github.com/autoworks-ai/autovault/actions/workflows/security.yml/badge.svg\"></a>\n  <a href=\"package.json\"><img alt=\"Node >=22\" src=\"https://img.shields.io/badge/node-%3E%3D22-339933\"></a>\n  <a href=\"LICENSE\"><img alt=\"License MIT\" src=\"https://img.shields.io/badge/license-MIT-blue\"></a>\n  <a href=\"docs/adr/0001-transport.md\"><img alt=\"MCP stdio + HTTP\" src=\"https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-6f42c1\"></a>\n</p>\n\n<p align=\"center\"><code>[ SKILL.md ] -> [ validate ] -> [ sign ] -> [ scope ] -> [ render ]</code></p>\n\n<p align=\"center\"><strong>A local-first vault for the skills your agents actually use.</strong></p>\n\n<p align=\"center\">\n  <video src=\"https://github.com/user-attachments/assets/8d23c38b-186a-424e-8e92-3dfdb82f143b\" width=\"760\"></video>\n</p>\n\n<p align=\"center\">\n  <sub>~48-second demo — dashboard and terminal use simulated skills and data.</sub>\n</p>\n\n`SKILL.md` files already move through GitHub repos, team docs, public indexes,\nSlack threads, and agent-written drafts. AutoVault gives those files one\ncanonical home: validate them at admission time, sign what passes, track where\nthey came from, and render the right view for each agent without maintaining\nforks by hand.\n\nAutoVault is a Node/TypeScript capability library, CLI, and MCP server. It has\nlocal stdio and remote Streamable HTTP MCP entry points, both backed by the same\nfilesystem vault and SQLite capability index.\n\nIt does **not** execute skills through the MCP server. The server validates and\nserves skill content; the host agent decides how to use that content inside its\nown tool sandbox. The separate user-invoked `autovault skill <action>` CLI can\nrun signed `bin:` actions from installed skills, and that surface is documented\nunder [Security Model](#security-model).\n\nDocs and public site: <https://autovault.dev>\n\n## Why AutoVault\n\nThe SKILL.md format is intentionally plain. The hard part is everything around\nit:\n\n- **Skill drift** - the same skill gets copy-pasted into Claude Code, Codex,\n  Cursor, and project folders with no upstream tracking.\n- **Supply-chain risk** - remote skill bytes should be treated like untrusted\n  package contents until they pass a gate.\n- **Duplicate explosion** - agents can author near-identical skills unless new\n  proposals are deduplicated before storage.\n- **Platform mismatch** - one agent says `read`, another says `file_read`, and a\n  third expects a different filesystem tool name.\n- **Scope leakage** - local dev skills should not silently show up in prod or in\n  another client's project.\n\nAutoVault's answer is deliberately simple: keep one canonical skill folder,\nrecord provenance, sign the admitted content, and sync or serve agent-specific\nviews from that source.\n\n## Quick Start\n\nRequirements:\n\n- Node.js `>=22.0.0`\n- `curl`, `tar`, and `npm`\n- macOS 13+, Linux x64/arm64, or Windows through WSL2\n\nInstall the local vault:\n\n```bash\ncurl -fsSL https://autovault.sh | sh\nexport PATH=\"$HOME/.autovault/bin:$PATH\"\nautovault --version\nautovault doctor\nautovault setup --review\nautovault skill list\n```\n\nInstall with Homebrew:\n\n```bash\nbrew install autoworks-ai/tap/autovault\nautovault setup\n```\n\nInstall the packaged CLI/library directly from npm:\n\n```bash\nnpm install -g @autoworks-ai/autovault\nautovault setup --review\nautovault doctor\n```\n\nManual source install:\n\n```bash\ngit clone https://github.com/autoworks-ai/autovault.git\ncd autovault\nnpm ci\nnpm run build\nnode scripts/bootstrap-skills.mjs\nnode dist/cli.js doctor\n```\n\nThe shell installer builds the app under `~/.autovault/app`, preserves\n`~/.autovault` as user-owned vault storage, installs the `autovault` CLI shim,\nand bootstraps bundled skills unless `AUTOVAULT_NO_BOOTSTRAP=1` is set. By\ndefault it installs the latest stable release; set `AUTOVAULT_REF=main` only\nwhen you explicitly want the unreleased main branch.\n\n## What Ships Today\n\nAutoVault supports:\n\n- local filesystem storage under `AUTOVAULT_STORAGE_PATH`\n- a SQLite capability index for callers, profiles, tool groups, aliases,\n  context rules, and MCP servers\n- per-agent and tag-filtered profile symlink generation\n- vault-local skill transforms that render agent-specific variants without\n  forking upstream `SKILL.md`\n- install, update, proposal, bulk-import, removal, resource-read, and drift-check\n  workflows\n- enrolled pull-sync for signed upstream skill releases over file catalogs and\n  HTTPS catalogs (`catalog.json` + `bundles/<bundle_hash>.json`), including\n  device enrollment, metadata-only update checks, local approval policy, bundle\n  verification, and revocation state\n- source adapters for GitHub, `agentskills`, arbitrary HTTPS URLs, local bundles,\n  and inline MCP-proposed content\n- three-tier deduplication for proposals\n- Ed25519 signatures and manifest checks for stored skills and executable\n  resources\n- local stdio MCP and remote Streamable HTTP MCP at `/mcp` with OAuth-backed\n  bearer auth\n\nThe npm package and Homebrew formula are live. The shell installer is still the\neasiest local bootstrap path because it provisions `~/.autovault`, installs the\nCLI shim, and seeds bundled skills in one pass.\n\nDistribution:\n\n- Source and releases: <https://github.com/autoworks-ai/autovault>\n- NPM package page: <https://www.npmjs.com/package/@autoworks-ai/autovault>\n- Homebrew tap: <https://github.com/autoworks-ai/homebrew-tap>\n- Container image: `ghcr.io/autoworks-ai/autovault:<tag>`\n\n## CLI Surface\n\nThe CLI is the local operator surface:\n\n```text\nautovault add <source-or-path> [--source github|agentskills|url|local] [--provenance <value>] [--version <v>] [--agent <agent>] [--sync-profiles|--no-sync-profiles] [--discover|--no-discover] [--link agent=/path/to/skills] [--dry-run] [--yes] [--quiet] [--verbose] [--json]\nautovault add-local <path> [--source <provenance>] [--sync-profiles] [--link agent=/path/to/skills] [--json]\nautovault remove <skill-name> [--discover|--no-discover] [--link agent=/path/to/skills] [--json]\nautovault sync-profiles [--discover] [--link agent=/path/to/skills] [--json]\nautovault profiles list [--json]\nautovault setup [--json] [--review] [--advanced]\nautovault doctor [skill-name] [--clean] [--repair] [--json]\nautovault audit-repo --repo /path/to/repo [--format json|markdown]\nautovault import-autohub --tool-filters /path/tool-filters.json [--mcp-servers /path/mcp-servers.json] [--reset] [--json]\nautovault link [slug|catalog-url|directory] [--json] [--no-browser]\nautovault resolve --caller <id> --platform <name> [--channel <id>] --query <text> [--json]\nautovault serve [--help]\nautovault ui [--port <n>] [--no-open]\nautovault skill list [--json]\nautovault skill search <query> [--top-k N] [--json]\nautovault skill which <name> [<action>]\nautovault skill <action> <name>\n```\n\nHuman-readable output is the default. Use `--json` or `--format json` only\nfor scripts and other machine consumers.\n\n`autovault ui` starts a loopback-only browser dashboard for local skill\nmetadata edits, named profile management, profile sync, update checks, deletion,\nsigned upstream update installs, enrolled-client revocation, and\npermission-group visibility. It serves the packaged React assets and uses the\nsame `/api/v1` management API shape as remote AutoVault.\n\n`autovault link` with no argument starts a Cloud device pairing: the CLI\nprints a short confirmation code, opens the browser, and polls until the\nowner confirms the code. The slug is no longer something a human types.\n`autovault link <slug|catalog-url|directory>` remains the fallback for older\nCloud enrollments and local catalogs (`init` stays a compatibility alias).\nHumans who already know a Cloud slug can still type `autovault link acme`;\nthe client expands that to `https://autovault.dev/v/<slug>/catalog.json`.\nOn a TTY the command waits for owner confirm/admit; `--json` and non-TTY\nruns return pending immediately, and a later `autovault link --json`\ncompletes pairing once the owner has confirmed. Override the Cloud origin with\n`AUTOVAULT_CLOUD_ORIGIN`. Pairing POSTs a self-signed device key to\n`/api/devices/pair` and polls `/api/devices/token`. Slug enrollment POSTs\nto `/v/<slug>/devices` and lands `pending` until the owner admits the\ndevice. Signed releases are discovered from `catalog.json` and\n`bundles/<bundle_hash>.json` and re-verified (release signature, bundle\nhash, per-file SHA-256) before install. Device requests are signed with\n`X-AutoVault-Device` / `-Timestamp` / `-Signature`. Beta limitation: if the live\ncatalog `public_key` drifts from the key pinned at enrollment, `readCatalog`\nhard-fails and every device must re-enroll.\n\nCommon flows:\n\n```bash\n# Inspect vault health and integrity.\nautovault doctor\nautovault doctor --clean\nautovault doctor --repair\n\n# Add a known skill from any supported source.\nautovault add ./path/to/your-skill --sync-profiles\nautovault add ./path/to/your-skill/SKILL.md --sync-profiles\nautovault add https://github.com/org/repo/tree/main/skills/your-skill\nautovault add owner/repo:skills/your-skill/SKILL.md\nautovault add my-skill --source agentskills\nautovault add https://example.com/SKILL.md --source url\n\n# Search installed skills locally.\nautovault skill search code-review --top-k 5\n\n# Link this machine to AutoVault Cloud, or a local test catalog.\nautovault link\nautovault link acme\nautovault link ./path/to/upstream-catalog\nautovault ui\n\n# Remove a vaulted skill and refresh managed profile links.\nautovault remove skill-author\n```\n\n`autovault add` is the canonical terminal path for known skills from local\nbundles, GitHub repositories, agentskills slugs, or HTTPS URLs. Existing\ninstaller scripts can keep using `add-local` as a compatibility alias for\nlocal bundles; there, `--source` still means local provenance. For new local\nadds, omit provenance and AutoVault records the normalized absolute bundle\ndirectory.\nIf a remote skill omits AutoVault-specific `agents` frontmatter, pass\n`--agent codex` (repeatable) for profile sync, or `--no-sync-profiles` for a\nvault-only install.\n\n### Doctor JSON and rendered state\n\n`autovault doctor --json` includes report-level render state alongside the\nordinary skill integrity results:\n\n- `render.index` is `absent`, `ok`, or `corrupt`.\n- `render.orphans` lists live managed symlinks with no backing index entry.\n- `render.unverifiable` lists render entries owned by skills that are no longer\n  installed.\n- Every skill has `render.kind`: `ok`, `skipped`, or `error`.\n\n`skipped` means that skill has no machine-local render entry; it is not an\nordinary doctor error. Automation consumers that require an installed and\nverified rendered bundle must positively assert `render.kind == \"ok\"` rather\nthan relying on the process exit code.\n\n`autovault setup` is the first-run adoption wizard. It scans the vault, bundled\nskills, and discovered native roots such as `~/.claude/skills`,\n`~/.codex/skills`, and `~/.cursor/skills`, then asks how to adopt each skill.\nRun it from a real terminal; without a TTY the installer defers setup and tells\nyou to rerun the wizard manually.\n\n## MCP Tool Surface\n\nMCP hosts can spawn the local stdio server with `node dist/index.js`, while\nremote clients connect to `dist/remote.js` at `/mcp`.\n\nRegistered tools:\n\n- `get_skill` - search by query or fetch by exact name, optionally rendering for\n  an agent and including packaged resources.\n- `add_skill` - install a known skill from `github`, `agentskills`, `url`, or\n  `local`.\n- `propose_skill` - submit newly authored SKILL.md bytes for validation,\n  security scan, deduplication, signing, and storage.\n- `bulk_import` - import every immediate child directory containing a `SKILL.md`.\n- `update_skill` - refresh from the recorded source or replace from a new\n  source, local bundle, or inline bytes.\n- `delete_skill` - remove an installed skill and its vault-local transforms,\n  then refresh generated profiles.\n- `check_updates` - compare installed skills against upstream source state and\n  report drift or transform-review work.\n\nTool handlers return plain objects. `src/mcp/server.ts` wraps and serializes\nthem into the MCP `content[0].text` envelope. Remote mode applies an additional\npolicy layer for scopes and skill visibility.\n\n## Library Surface\n\nThe source package exports the same helpers used by the CLI and MCP server:\n\n- `resolveCapabilities()` / `resolve_capabilities()`\n- `syncProfiles()` and `discoverProfileRoots()`\n- `addSkill()`, `updateSkill()`, `deleteSkill()`, `installSkill()`,\n  `addLocalSkill()`, `proposeSkill()`, and `bulkImport()`\n- `proposeSkillTransform()`, `listSkillTransforms()`,\n  `removeSkillTransform()`, and `renderSkillForAgent()`\n- `auditRepo()`\n- `importAutohubCapabilities()` / `ensureAutohubSeeded()`\n\nUnknown callers fail closed. Register callers explicitly or map unknown users to\na restricted caller such as `guest`.\n\n## Validation Gate\n\nEvery install, update, proposal, and bulk import runs through the same\nvalidation path:\n\n1. Repair and normalize frontmatter formatting.\n2. Parse YAML frontmatter with `gray-matter`.\n3. Validate schema with `zod`.\n4. Scan content against the denylist in `scripts/security/patterns.json`.\n5. Cross-check declared capabilities against observed behavior.\n6. Deduplicate exact, near-exact, and functionally similar proposals.\n7. Write the skill, source sidecar, signed manifest, and Ed25519 signature.\n\nIn strict mode (`AUTOVAULT_SECURITY_STRICT=true`, the default), denylist hits\nblock writes. In non-strict mode they become warnings.\n\n## Storage Layout\n\nDefault storage is `~/.autovault`; override it with\n`AUTOVAULT_STORAGE_PATH`.\n\n```text\n$AUTOVAULT_STORAGE_PATH/\n  autovault.sqlite             # capability index\n  .signing-key.json            # Ed25519 keypair, mode 0600\n  skills/\n    <name>/\n      SKILL.md\n      .autovault-source.json   # source, hash, timestamps\n      .autovault-signature     # detached Ed25519 signature, mode 0600\n      .autovault-manifest      # signed manifest for declared resources/bin\n      <resources...>\n  transforms/\n    <base-skill>/<transform>/\n      TRANSFORM.md\n      BASE_SKILL.md\n      .autovault-transform.json\n      .autovault-manifest\n  rendered/\n    <agent>/<skill>/            # generated variants\n  profiles/\n    <agent>/<skill-name> -> ../../skills/<skill-name> or ../../rendered/<agent>/<skill-name>\n    <named-profile>/<skill-name> -> ../../skills/<skill-name> or ../../rendered/<agent>/<skill-name>\n  profiles.config.json\n  cloud-sync/\n    upstreams.json             # enrolled upstream/device metadata, mode 0600\n```\n\nSkills are plain files. Back them up like dotfiles:\n\n```bash\ntar -czf autovault-backup-$(date +%F).tgz -C \"$HOME\" .autovault\n```\n\n## Skill Transforms\n\nTransforms let a workspace or agent adjust a skill without editing the upstream\n`SKILL.md`. AutoVault stores the transform under the vault, appends transform\ninstructions to the base skill at render time, applies declared capability\nmetadata overrides, and materializes generated variants under `rendered/`.\n\nExample `TRANSFORM.md`:\n\n```yaml\n---\nname: perplexity\nbase: research-skill\ndescription: Use Perplexity instead of the default web search path.\ntargets:\n  agents: [codex]\npriority: 100\ncapability_overrides:\n  network: true\n  tools:\n    add: [mcp__perplexity__search]\n    remove: [web_search]\nmetadata:\n  version: \"1.0.0\"\n---\n\nUse `mcp__perplexity__search` instead of `web_search` for research.\n```\n\nWhen the base skill changes, `check_updates` continues rendering the transform\nbut returns `transform_reviews` with the pinned old base so the delta can be\nreviewed.\n\n## Remote Deploy\n\nRemote mode is for a shared or managed vault. It serves Streamable HTTP MCP at\n`/mcp`, uses OAuth for client registration/login/token issuance, and stores the\nvault under the mounted `AUTOVAULT_STORAGE_PATH`.\n\n```bash\nnpm run build\nAUTOVAULT_MODE=remote \\\nAUTOVAULT_PUBLIC_URL=http://localhost:3000 \\\nAUTOVAULT_ADMIN_EMAIL=admin@example.com \\\nAUTOVAULT_ADMIN_PASSWORD=replace-with-a-long-random-password \\\nnpm run start:remote\n```\n\nDocker:\n\n```bash\nAUTOVAULT_ADMIN_EMAIL=admin@example.com \\\nAUTOVAULT_ADMIN_PASSWORD=replace-with-a-long-random-password \\\ndocker compose up --build\n```\n\nRemote mode cannot create symlinks on client machines. `sync-profiles` is\nlocal-only because a remote MCP server has no filesystem access to\n`~/.codex/skills`, `~/.claude/skills`, or other host roots. Remote clients\nshould discover and read skills directly through `get_skill`.\n\n## Configuration\n\nRuntime environment:\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `AUTOVAULT_MODE` | `local` | `local` for stdio/library use, `remote` for HTTP MCP. |\n| `AUTOVAULT_STORAGE_PATH` | `~/.autovault` | Root path for installed skills. |\n| `AUTOVAULT_DB_PATH` | `$AUTOVAULT_STORAGE_PATH/autovault.sqlite` | SQLite capability index. |\n| `AUTOVAULT_PROFILE_LINKS` | unset | Comma-separated `agent=/skills/root` links for profile sync. |\n| `AUTOVAULT_PROFILE_CONFIG_PATH` | `$AUTOVAULT_STORAGE_PATH/profiles.config.json` | Optional named profile config. |\n| `AUTOVAULT_SKILL_INSTALL` | `prefer-autovault` | Vendor routing: `prefer-autovault`, `both`, `native`, `native-only`, or `off`. |\n| `AUTOVAULT_SECURITY_STRICT` | `true` | Block denylist hits when true; warn when false. |\n| `AUTOVAULT_SEARCH_MODE` | `text` | Search backend. Metadata text search is the current implementation. |\n| `AUTOVAULT_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error`. |\n| `AUTOVAULT_LOG_DIAGNOSTICS` | unset | Set to `1` to let structured diagnostic logs pass through public CLI output suppression. |\n| `AUTOVAULT_PUBLIC_URL` | required in remote mode | Public origin for OAuth metadata and callbacks. |\n| `AUTOVAULT_HTTP_PORT` | `3000` | HTTP port when `PORT` is not injected by the platform. |\n| `AUTOVAULT_ALLOWED_ORIGINS` | unset | Optional CORS allowlist for remote mode. |\n| `AUTOVAULT_ADMIN_EMAIL` | required until owner exists | First remote owner email. |\n| `AUTOVAULT_ADMIN_PASSWORD` | required until owner exists | First remote owner password, at least 12 characters. |\n| `GITHUB_TOKEN` | unset | Optional GitHub API rate-limit headroom. |\n| `AUTOVAULT_AGENTSKILLS_BASE` | `https://agentskills.io/api/v1` | Override the agentskills API base. |\n\nInstaller-only environment:\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `AUTOVAULT_HOME` | `~/.autovault` | Install root for app, shim, and default storage. |\n| `AUTOVAULT_BIN_DIR` | `$AUTOVAULT_HOME/bin` | Directory for the `autovault` shim. |\n| `AUTOVAULT_REF` | latest stable release | GitHub branch or tag downloaded by `autovault.sh`; use `main` for the unreleased branch. |\n| `AUTOVAULT_TARBALL_URL` | derived from `AUTOVAULT_REF` | Fully override the source archive URL. |\n| `AUTOVAULT_NO_BOOTSTRAP` | `0` | Set to `1` to skip bundled-skill bootstrap. |\n\n## Security Model\n\nAutoVault has two execution surfaces with different boundaries.\n\n**The MCP servers** (`dist/index.js` over stdio and `dist/remote.js` over\nStreamable HTTP) are storage-and-validation services. They never execute skill\ncontent. Remote sources are treated as untrusted input and must pass schema,\nsecurity, capability, dedup, signing, and path-safety checks before any write.\nAll diagnostics go to stderr so stdout stays reserved for stdio MCP framing.\nRemote mode additionally requires OAuth bearer tokens and filters skill\nvisibility for non-owner users.\n\n**The `autovault skill <action>` CLI** is a user-invoked execution surface for\nskills that declare signed `bin:` actions. It runs the script as the invoking\nuser, with that user's filesystem and network access. Before execution, the CLI\nhard-fails if the signed manifest, `SKILL.md`, or declared bin resources have\nbeen changed post-install.\n\nImportant limits:\n\n- The trust root is the keypair at `$AUTOVAULT_STORAGE_PATH/.signing-key.json`.\n  Treat storage-root write access as full vault compromise.\n- `autovault doctor --clean` removes only ignored OS/editor metadata such as\n  `.DS_Store`, `Thumbs.db`, `desktop.ini`, and AppleDouble `._*` files.\n- Unknown hidden files, symlinks, special files, unsigned helpers, and changed\n  signed files remain integrity failures.\n- The CLI requires an interactive TTY for bin actions as defense in depth, but a\n  pseudo-terminal can satisfy that check. The hard boundary is validation plus\n  manifest signing, not proof of a human at the keyboard.\n\nFor the full model and accepted risks, read\n[`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md).\n\n## Development\n\n```bash\nnpm ci\nnpm run build\nnpm test\nnode scripts/smoke.mjs\nnode scripts/remote-smoke.mjs\nnode scripts/probe.mjs\n```\n\nThe smoke, probe, and remote-smoke scripts require `npm run build` first because\nthey spawn compiled files from `dist/`.\n\n### Fresh Installer Sandbox\n\nUse this when you want to walk through the shell installer like a new user\nwithout touching your real `~/.autovault`, shell profile, or installed skills.\nThe recipe packages the current development checkout, including uncommitted\nfiles, and points the installer at that local archive.\n\n```bash\nSANDBOX=\"$(mktemp -d -t autovault-fresh.XXXXXX)\"\nFRESH_HOME=\"$SANDBOX/home\"\nARCHIVE=\"$SANDBOX/autovault-dev.tgz\"\nmkdir -p \"$FRESH_HOME\"\n\ntar \\\n  --exclude ./.git \\\n  --exclude ./node_modules \\\n  --exclude ./dist \\\n  -czf \"$ARCHIVE\" \\\n  -C \"$(dirname \"$PWD\")\" \"$(basename \"$PWD\")\"\n\nHOME=\"$FRESH_HOME\" \\\nAUTOVAULT_HOME=\"$FRESH_HOME/.autovault\" \\\nAUTOVAULT_BIN_DIR=\"$FRESH_HOME/.autovault/bin\" \\\nAUTOVAULT_TARBALL_URL=\"file://$ARCHIVE\" \\\nAUTOVAULT_REF=dev \\\nsh scripts/install.sh --verbose\n```\n\nAfter install, keep the sandboxed `HOME` and `PATH` on commands you want to run\nfrom the new-user perspective:\n\n```bash\nHOME=\"$FRESH_HOME\" PATH=\"$FRESH_HOME/.autovault/bin:$PATH\" autovault --version\nHOME=\"$FRESH_HOME\" PATH=\"$FRESH_HOME/.autovault/bin:$PATH\" autovault doctor\nHOME=\"$FRESH_HOME\" PATH=\"$FRESH_HOME/.autovault/bin:$PATH\" autovault skill list\nHOME=\"$FRESH_HOME\" PATH=\"$FRESH_HOME/.autovault/bin:$PATH\" autovault ui --no-open --port 0\n```\n\nTo skip the setup wizard during install and run it manually:\n\n```bash\nHOME=\"$FRESH_HOME\" \\\nAUTOVAULT_HOME=\"$FRESH_HOME/.autovault\" \\\nAUTOVAULT_BIN_DIR=\"$FRESH_HOME/.autovault/bin\" \\\nAUTOVAULT_TARBALL_URL=\"file://$ARCHIVE\" \\\nAUTOVAULT_REF=dev \\\nAUTOVAULT_NO_SETUP=1 \\\nsh scripts/install.sh --verbose\n\nHOME=\"$FRESH_HOME\" PATH=\"$FRESH_HOME/.autovault/bin:$PATH\" autovault setup --review\n```\n\nRemove the whole sandbox when finished:\n\n```bash\nrm -rf \"$SANDBOX\"\n```\n\nArchitecture map:\n\n- `src/index.ts` - local stdio MCP entry point\n- `src/remote.ts` - remote Streamable HTTP MCP entry point\n- `src/mcp/` - tool registration and serialization\n- `src/tools/` - MCP tool handlers\n- `src/cli/` - local operator CLI and UI\n- `src/library.ts` - public ESM exports\n- `src/capabilities/` - SQLite schema, resolver, AutoHub import\n- `src/profiles/` - profile discovery, filtering, and symlink sync\n- `src/validation/` - frontmatter repair, schema, security, dedup\n- `src/sources/` - source adapters\n- `src/storage/` - filesystem storage, locks, manifests, signing\n- `src/util/` - shared helpers\n\nRelease and operations docs:\n\n- [`INSTALL.md`](INSTALL.md)\n- [`CHANGELOG.md`](CHANGELOG.md)\n- [`docs/RELEASE.md`](docs/RELEASE.md)\n- [`docs/adr/0001-transport.md`](docs/adr/0001-transport.md)\n\n## Roadmap\n\nLikely next areas:\n\n- stronger key storage for signature enforcement\n- semantic search via local embeddings\n- additional source adapters such as ClawHub, LobeHub, and Tessl\n- local mirror helper for permitted remote skills\n- secret resolver design, without storing secret values in the vault\n","readmeFilename":"README.md"}