agent-skillboard 0.2.18 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+## 0.3.0 — 2026-07-13
+
+### Changed
+
+- Replaced the v1 policy matrix with schema v2's user-level decisions:
+  enable/disable and explicit per-skill cross-agent sharing.
+- Made valid installed skills enabled and agent-local by default; `shared: true`
+  preserves originals while creating managed compatible copies.
+- Added generated `installed_on` inventory so route and guard evaluate the
+  selected agent without a user-managed agent matrix.
+- Made normal setup, brief, route, guard, and policy mutations use home state
+  from any working directory; project init is no longer part of the v2 flow.
+- Limited optional preference to candidate ranking; preference never changes
+  availability or sharing.
+- Moved source, provenance, install-unit, digest, alias, and risk observations to
+  optional generated audit metadata that cannot block a skill.
+- Added explicit preview, apply, and byte-restoring rollback documentation for
+  `skillboard migrate v2`.
+- Scheduled removal of the one-release v1 read-only compatibility window for
+  v0.4.0.
+- Added `skill forget` for explicit policy-only cleanup after an owning
+  installer removes a local skill.
+- Added `uninstall --user` dry-run and confirmed apply flows that remove all
+  marker-owned shared copies, managed guidance, and home state while preserving
+  agent-owned and unmanaged skills.
+- Restored the declared Node.js 14.21 runtime floor and added release gates for
+  Node.js 14.21, 20, and 22 on Ubuntu, macOS, and Windows.
+
+### Fixed
+
+- Prevented removed skills from leaving unrecoverable stale policy that keeps
+  doctor unhealthy.
+- Prevented package removal from orphaning SkillBoard-managed shared copies in
+  supported agent skill roots.
+- Replaced Node 15/16-only clone, string replacement, recursive copy, and npm
+  smoke-test APIs with Node.js 14.21-compatible paths.
+
+### Security
+
+- Clarified that SkillBoard does not authorize hooks, MCP servers, commands,
+  external writes, destructive actions, or secrets; those remain runtime and
+  harness permission decisions.
+
 ## 0.2.18 — 2026-07-07
 
 ### Changed

package/README.md

@@ -1,298 +1,169 @@
 # SkillBoard
 
-Keep AI-agent skills broadly available, then route overlaps consistently.
-
-If you use more than one coding agent, skill pack, plugin, MCP tool, or
-marketplace, SkillBoard answers the practical questions before you install
-anything or change workflow policy: which skills are usable now, which one
-should win when skills overlap, which external skills need review, and how
-Codex, Claude, OpenCode, and Hermes can follow the same policy.
-
-Ask your AI normal work requests: "write tests before implementation",
-"review this plan and point out weak assumptions", "help me refine this UX
-flow", or explicit control requests like "use the Codex test-first skill in
-OpenCode too." SkillBoard runs behind the scenes only when skill choices
-overlap, workflow priority matters, or you explicitly ask for a skill/control
-decision, so you get the benefit: broadly available skills, one routed skill
-when similar skills overlap, and a short disclosure of what was used.
-
-The burden stays low:
-
-- No global install is required for a trial; use
-  `npm exec --yes --package agent-skillboard@latest -- skillboard`.
-- Most use is read-only: `brief`, `route`, and `guard use` answer what can run
-  now and which route fits the request; `doctor` checks local policy and source
-  health without writing changes.
-- Nothing changes until you approve a policy action.
-- Agent-layer cleanup is previewable with
-  `skillboard uninstall --agent-layer --dry-run`; it removes only managed
-  SkillBoard guidance while preserving other agent skills.
-
-Status: public alpha. The current config schema is config schema v1; breaking
-changes may still happen before `1.0.0` and are documented in release notes.
-
-Under the hood, SkillBoard is workflow-scoped skill priority and overlap routing
-for AI agents. Installed user skills are usable by default unless runtime, user,
-or local instructions disable them; SkillBoard helps Codex, OpenCode, Claude,
-and Hermes resolve overlapping skills and workflow priority instead of guessing
-from raw skill files.
-
-Start with normal requests:
-
-- "What skills can you use in this project?"
-- "Write tests before implementation."
-- "Review this plan and point out weak assumptions."
-- "Help me refine this UX flow."
-- "Use the Codex test-first skill in OpenCode too."
-- "Can you make `anthropic.docx` available for this workflow?"
-- "Why is this skill blocked?"
-
-Your AI runs SkillBoard behind the scenes, reads the current brief, checks the
-guard automatically before invoking an allowed skill, and asks only before
-policy-changing actions. For already-allowed skills, it should say which skill
-it is about to use and which skill it used, not interrupt you for another
-approval. That disclosure is an audit trace, not a permission prompt. You do
-not need to memorize the SkillBoard command loop.
-
-A normal allowed-skill turn can look like this:
-
-- You: "Write tests before implementation."
-- AI: "I will use matt.tdd for this request."
-- AI: "I used matt.tdd for this request."
-
-Names you may see in setup and logs:
-
-- `SkillBoard`: the product and policy model.
-- `agent-skillboard`: the npm package.
-- `skillboard`: the CLI binary.
-
-## Who This Is For
-
-Use SkillBoard if you use more than one coding agent, skill pack, plugin, MCP
-tool, or marketplace and want one answer to:
-
-- Which skills can this agent use right now?
-- Which skill should win when several match the same task?
-- Which external or plugin skills are reviewed, blocked, or waiting for approval?
-- How can Codex, Claude, OpenCode, and Hermes follow the same skill policy?
-
-If you use one agent with a few hand-written local skills, you probably do not
-need SkillBoard yet. SkillBoard is for setups that have grown beyond one trusted
-skill folder and need workflow-scoped control without turning skill governance
-into a manual checklist.
-
-If you are changing routing, brief, bridge, policy, or workflow UX, read
-[AI Skill Routing Goal](docs/ai-skill-routing-goal.md) first; it defines the
-non-blocking `observe → route → work → explain briefly → ask after → remember
-policy` loop that development should preserve.
+SkillBoard gives AI agents one small user-level policy for installed skills:
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram: sources, inventory scanner, SkillBoard model, policy engine, and user and agent surfaces." width="100%">
-</p>
-
-## Why Not Just List `/skills`?
-
-A raw skill list answers what is declared. SkillBoard answers what can run now
-and how overlapping matches should route.
+1. Enable or disable a skill.
+2. Keep an enabled skill agent-local or shared across agents.
 
-Same fixture, different answer:
+Valid installed skills default to enabled and agent-local. Sharing is opt-in per
+skill. Optional preference ranks enabled skills installed for the current agent
+and never changes availability or copies files.
 
-| Raw skill list | SkillBoard brief |
-| --- | --- |
-| `matt.tdd active workflow-auto` | `AI can use now: 0` |
-| no policy health | `Blocked for safety: 8`, `Policy errors: 2` |
-| several review skills look relevant | `Overlap: Multiple allowed skills match... routes ...` |
+Status: public alpha. Package 0.3.0 writes policy schema v2.
 
-That gap is the product. SkillBoard separates `installed` from `available`,
-checks policy health, and gives agents a route they can use without guessing
-from raw `SKILL.md` files. The same proof also routes "write tests before
-implementation" to `matt.tdd`, returns `private.tdd-work-continuity` as the
-fallback, and gives the AI exact start and finish disclosure text. Targeted
-tests also cover `grill-me`-style review overlap across Codex and OpenCode
-workflows.
-
-See [Tested Value Proof](#tested-value-proof) for the executable proof.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
+</p>
 
 ## 5-Minute Quick Start
 
-Try it without a global install. These read-only commands download the latest
-package for one run and do not create project files:
+Try the read-only CLI:
 
 ```bash
 npm exec --yes --package agent-skillboard@latest -- skillboard --version
-npm exec --yes --package agent-skillboard@latest -- skillboard help brief
+npm exec --yes --package agent-skillboard@latest -- skillboard help
 ```
 
-Install the CLI when you want SkillBoard connected to your agent layer. On a
-normal global install, SkillBoard auto-connects the agent layer for detected
-Codex, Claude, OpenCode, and Hermes user skill roots:
-
-AI/automation/operator details:
+Install globally:
 
 ```bash
 npm install -g agent-skillboard
 ```
 
-If your system npm requires elevated permissions, `sudo npm install -g
-agent-skillboard` is also supported. In that flow, install-time setup resolves
-`SUDO_USER` and writes the user-level guidance skill under the invoking user's
-agent homes. Managed guidance files written under the user's home are restored
-to the invoking user's ownership, while the `skillboard` binary still lands in
-the global prefix used by that npm command.
-
-The install-time setup writes a user-level `skillboard` guidance skill under
-detected agent homes. For Codex, detection includes `CODEX_HOME/skills`,
-`AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.
-If `~/.agents` already exists, setup creates `~/.agents/skills` because that is
-the shared Codex-visible skill tree in LazyCodex-style environments.
-It does not create `skillboard.config.yaml`,
-`.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects.
-No separate setup command is required after a normal global install or update:
-npm lifecycle scripts run agent-layer setup automatically, rerun the agent-home
-scan, refresh managed SkillBoard guidance files, and add newly detected
-supported agent roots. This setup is agent-layer only.
-
-Run `skillboard setup --agent codex,claude,opencode,hermes --yes` later only
-after adding another supported agent, enabling a new agent home, or installing
-with lifecycle scripts disabled. Restart or refresh agents that cache user
-skills, then ask normal questions:
-
-- "Write tests before implementation."
-- "Review this plan and point out weak assumptions."
-- "What skills can you use here?"
-- "Use the Codex test-first skill in OpenCode too."
-- "When two skills overlap, which one should take priority?"
-
-When a target agent needs a skill from another agent, it can use
-`skillboard import-skill --from codex --to opencode --skill <skill> --json`
-behind the scenes. Compatible skills are copied into the target agent's user
-skill root. If the source contains agent-specific instructions, the agent asks
-before creating an adapted target-agent `SKILL.md` and installs that file with
-provenance.
-
-Remove SkillBoard's managed agent-layer guidance before package removal when
-you want agent homes back to their pre-SkillBoard guidance state:
+The package postinstall sets up detected agent guidance and creates the
+user-level state at `~/skillboard.config.yaml` and
+`~/.skillboard/inventory.json`. No separate setup command is required after a
+normal install. If lifecycle scripts were skipped or another agent was added:
 
 ```bash
-npx --yes --package agent-skillboard skillboard uninstall --agent-layer --dry-run
-npx --yes --package agent-skillboard skillboard uninstall --agent-layer
-npm uninstall -g agent-skillboard
+skillboard setup --agent codex,claude,opencode,hermes --yes
+```
+
+`sudo npm install -g agent-skillboard` is supported when system npm requires
+it. Setup resolves `SUDO_USER` and restores managed home files to that user.
+Setup and ordinary use write no project policy and require no project init.
+
+Ask the agent for the work you want. SkillBoard is consulted when skills overlap
+or when you ask which skill should be used.
+
+## The v2 policy
+
+```yaml
+version: 2
+skills:
+  test-first:
+    enabled: true
+    shared: false
+    preference:
+      intents: [testing]
+      priority: 100
+  docs-helper:
+    enabled: true
+    shared: true
+  unused:
+    enabled: false
+    shared: false
 ```
 
-Agent-layer uninstall removes only managed `skillboard/SKILL.md` guidance files
-that contain SkillBoard's integration marker. It preserves other agent skills
-and user-authored `skillboard` skills.
-
-See [docs/install.md](docs/install.md) for global installs, `--dir`, GitHub
-builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
-
-## What SkillBoard Gives You
-
-- Inventory that separates installed skills from callable skills.
-- Broad default availability with workflow-scoped overlap routing.
-- `brief`, `route`, `can-use`, and `guard use` surfaces for AI-mediated selection and availability.
-- `import-skill` for agent-layer skill reuse across Codex, Claude, OpenCode, and Hermes.
-- Workflow conflict checks and overlap summaries so similar skills stay
-  available without quietly degrading an answer.
-- Action cards that apply one approved policy change, then re-resolve state.
-- Source and install-unit review for plugins, hooks, MCP servers, harnesses,
-  commands, LSPs, and package-manager dependencies.
-- Impact, reconcile, rollout, and dashboard output before cleanup or migration.
-- Manual skill variant lifecycle for relationships such as `a -> claude.a`,
-  with draft, approval, drift, and reset checkpoints.
-
-SkillBoard is priority-first at the agent layer: installed user skills are
-usable unless runtime, user, or local instructions disable them. Local workspace
-policy files can still model stricter workflow, source, and invocation
-decisions when a team needs that control.
-For action cards, use `skillboard apply-action <action-id> --yes --json`; raw
-`skillboard hook install ... --dry-run --json` previews are underlying manual
-operator detail, not the primary action-card flow.
-
-## Legacy Project Policy Mode
-
-Legacy project policy mode is for existing workspaces that still carry local
-SkillBoard policy files.
-
-`skillboard init` is deprecated project-local policy bootstrap and is not
-needed for normal use. Global install/postinstall and `skillboard setup`
-connect SkillBoard at the agent layer without creating `skillboard.config.yaml`,
-`.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects. Agent-layer setup does
-not run `skillboard init`.
-
-The command remains for existing workspaces that intentionally maintain local
-policy files, bridge guidance, and reports. Use `skillboard help init` before
-using it in an existing workspace.
-
-Default legacy project uninstall removes SkillBoard config, bridge guidance,
-and `.skillboard/` project state while preserving local `skills/*/SKILL.md`
-files:
+`enabled` controls use. `shared` controls whether SkillBoard maintains compatible
+copies for other supported agents. `shared: false` leaves the skill where its
+owner installed it; it does not quarantine, isolate, move, or delete anything.
+`shared: true` preserves the owner copy and adds only managed shared copies.
+
+New valid skills receive `enabled: true` and `shared: false`. See
+`examples/v2-multi-source.config.yaml` for a valid policy and
+`examples/v2-policy-error.config.yaml` for a validation fixture. Unprefixed
+examples are retained only as v1 migration fixtures.
+
+Generated inventory records where a skill is installed through `installed_on`.
+Source, provenance, path, digest, aliases, install-unit details, and risk are
+optional audit metadata and never determine availability. Runtime and action
+authorization are outside SkillBoard's scope; the active agent or harness still
+authorizes commands, hooks, MCP servers, network access, external writes,
+destructive actions, and secrets.
+
+## Agent flow
+
+From any working directory, an agent can:
+
+1. Read `skillboard brief --intent <request> --agent <agent> --json`.
+2. Select an enabled skill installed for that agent, using preference only to
+   rank matches.
+3. Run `skillboard guard use <skill-id> --agent <agent> --json` before use.
+4. Work without another approval when the guard allows use.
+5. Ask after completion only if remembering a preference would help.
+
+Direct policy changes are:
+
+```bash
+skillboard skill enable <skill-id>
+skillboard skill disable <skill-id>
+skillboard skill share <skill-id>
+skillboard skill unshare <skill-id>
+skillboard skill preference <skill-id> --intent <term>[,<term>] --priority <integer>
+skillboard skill forget <skill-id>
+```
+
+Add `--dry-run` to preview or `--json` for machine-readable output. For mediated
+changes, the agent reads `brief --include-actions --json`, asks once about one
+current action, runs `skillboard apply-action <action-id> --agent <agent> --yes --json`, and
+rereads the returned post-apply brief.
+
+This is the distinction from a pure distribution tool: skills stay local by
+default, users promote only selected skills to shared use, and routing preference
+can be remembered without changing installation or availability.
+
+## Migrate version 1
+
+Version 1 has a one-release read-only window beginning in v0.3.0. Preview makes
+no writes; apply creates an adjacent byte-for-byte backup; rollback restores it.
 
 ```bash
-skillboard uninstall --dir /path/to/your/project --dry-run
-skillboard uninstall --dir /path/to/your/project
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-Use `--keep-settings` only when you want to keep legacy project policy and
-bridge guidance in place, for example while cleaning generated helper files.
-`--purge` remains accepted as an explicit spelling for the default clean
-project removal.
+All v1 mutations refuse and point to migration. v0.4.0 removes the v1 reader.
 
-## What Works Today
+## Cleanup
 
-SkillBoard currently supports:
+After removing a local skill with its owning agent or package manager, refresh
+inventory and explicitly forget the stale policy entry:
 
-- YAML policy config parsing and semantic checks.
-- Recursive `SKILL.md` discovery.
-- Source-profile import for cloned or installed skill repositories.
-- Agent runtime install-unit inventory when manifest metadata is available.
-- Markdown dashboard and machine-readable brief generation.
-- Disable-impact analysis and reconcile plans.
-- Workflow-scoped activation, blocking, preference, and guard checks.
-- Action-card approval and post-apply brief refresh.
-- Agent-layer skill import with compatible copy or user-approved AI-mediated adaptation.
-- Manual variant registration, fork, status, approval, and reset.
+```bash
+skillboard inventory refresh
+skillboard skill forget <skill-id> --dry-run
+skillboard skill forget <skill-id>
+```
 
-For the full command catalog and config shape, use
-[docs/reference.md](docs/reference.md).
+`forget` never deletes skill files. It refuses skills that are still observed or
+shared, so shared skills must be unshared first.
 
-## Tested Value Proof
+Before removing the SkillBoard package, preview and apply the complete
+user-level cleanup:
 
-A raw list says `matt.tdd` is active. SkillBoard says the same workflow has 0
-usable skills because policy health fails.
+```bash
+skillboard uninstall --user --dry-run
+skillboard uninstall --user --yes
+npm uninstall -g agent-skillboard
+```
 
-| Question | Raw list | SkillBoard brief |
-| --- | --- | --- |
-| Does `matt.tdd` look enabled? | `active`, `workflow-auto` | blocked by policy health |
-| Can the agent safely use anything now? | not answered | 0 usable skills, 8 blocked skills |
-| Why? | not answered | `Policy errors: 2`, `Policy warnings: 1` |
+User cleanup removes marker-owned shared copies, managed guidance, the home
+policy, and generated user state. It preserves agent-owned and unmanaged skills.
+Legacy project and guidance-only cleanup remain available through command help.
 
-The action-card flow is tested too. Applying
-`activate-skill:anthropic.docx` in a temporary project changes the next brief
-from 2 usable skills to 3 and moves `anthropic.docx` into the manual-allowed
-set. SkillBoard applies one approved change, then re-resolves the next state.
+## Development
 
-Run the proof with:
+From a clone, replace `skillboard ` with `node bin/skillboard.mjs `.
 
 ```bash
-node --test test/readme-value-proof.test.mjs
+npm install
+npm run check
+node bin/skillboard.mjs help
 ```
 
-See the [full reproducible proof](docs/value-proof.md) for exact commands,
-fixtures, and assertions.
-
-## Where To Go Next
-
-- [AI skill routing goal](docs/ai-skill-routing-goal.md)
-- [Install and agent-layer setup](docs/install.md)
-- [First-time control flow](docs/user-flow.md)
-- [Capability routing](docs/routing.md)
-- [Command and config reference](docs/reference.md)
-- [Policy model](docs/policy-model.md)
-- [Capabilities](docs/capabilities.md)
-- [Skill variant lifecycle](docs/variant-lifecycle.md)
-- [Value proof](docs/value-proof.md)
-- [Source-profile adapters](docs/adapters.md)
-- [Rollout runbook](docs/rollout-runbook.md)
-- [Versioning and release rules](docs/versioning.md)
-- [Contributing](CONTRIBUTING.md)
+Read [installation](docs/install.md), [user flow](docs/user-flow.md),
+[policy model](docs/policy-model.md), [routing](docs/routing.md),
+[reference](docs/reference.md), [versioning](docs/versioning.md), and the
+[Rollout runbook](docs/rollout-runbook.md).

package/docs/adapters.md

@@ -1,127 +1,51 @@
 # Adapter Model
 
-SkillBoard should not hardcode one adapter per popular repository.
-
-The core should stay generic, and repository-specific behavior should live in
-data-driven source profiles wherever possible.
+Adapters discover skills and runtime components. They do not decide whether a
+skill is available.
 
 ## Layers
 
-1. Core scanners
-
-   Generic code that understands common primitives:
-
-   - `SKILL.md` folders with YAML frontmatter;
-   - plugin or marketplace manifests;
-   - package manager metadata;
-   - known user/project install scopes;
-   - command, hook, MCP, agent, and LSP component lists.
-
-2. Source profiles
-
-   Declarative profiles that describe how to interpret a source:
-
-   ```yaml
-   id: github.mattpocock.skills
-   source: mattpocock/skills
-   kind: marketplace
-   namespace: matt
-   target_path_prefix: matt
-   default_status: vendor
-   default_invocation: manual-only
-   default_exposure: exported
-   skill_paths:
-     - "skills/**/SKILL.md"
-     - "*/SKILL.md"
-   category_path_segment: 1
-   path_rules:
-     - pattern: "skills/deprecated/**/SKILL.md"
-       status: deprecated
-       invocation: deprecated
-       category: deprecated
-   ```
-
-   A profile can set namespace, default policy, component mapping, known manifest
-   paths, category extraction, lifecycle overrides, and risk hints without
-   requiring code changes.
-
-   `category_path_segment` reads a slash-separated path segment from the matched
-   `SKILL.md` path. For example, `skills/engineering/tdd/SKILL.md` with segment
-   `1` becomes category `engineering`. `path_rules` apply first-match overrides
-   for repository conventions such as `deprecated` or `in-progress` folders.
-
-3. Detector plugins
-
-   Code adapters are only for sources whose layout cannot be described
-   declaratively, such as installers that mutate multiple config files or require
-   command output parsing. These should be small detector modules that produce the
-   same install-unit data model as profiles.
-
-## Built-In Profiles Are Not Hardcoding
-
-SkillBoard can ship built-in profiles for popular ecosystems, but they should be
-treated as bundled data, not product logic. Users and communities should be able
-to add or override profiles without forking the CLI.
-
-Good built-ins:
-
-- `mattpocock/skills`: skill pack profile.
-- `code-yeongyu/oh-my-openagent`: harness/plugin bundle profile.
-- `anthropics/skills`: standard Agent Skills profile.
-- `wshobson/agents`: marketplace/plugin profile.
-- `VoltAgent/awesome-agent-skills`: catalog profile.
-
-Bad design:
-
-- `if repo === "mattpocock/skills"` branches in the import logic;
-- repo-specific policy decisions embedded in TypeScript;
-- automatic global activation because a known repository was installed.
-
-## Import Output Contract
-
-Every profile or detector should output the same normalized shape:
-
-- install units;
-- declared skills;
-- owner links via `owner_install_unit`;
-- component lists;
-- guessed capabilities;
-- default invocation and exposure;
-- warnings and decisions requiring user approval.
-
-Current CLI surface:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
+1. Core scanners read common `SKILL.md`, manifest, package, and component shapes.
+2. Source profiles describe repository paths and stable id mapping as data.
+3. Detector plugins handle installers whose layout cannot be expressed by a
+   profile.
+
+Every layer produces deterministic generated inventory. Source, provenance,
+path, digest, aliases, install-unit, and runtime-component observations are
+optional audit metadata and never determine availability.
+
+## Profile example
+
+```yaml
+id: example-pack
+source: example/skills
+namespace: example
+skill_paths:
+  - "skills/**/SKILL.md"
+path_rules:
+  - pattern: "skills/deprecated/**/SKILL.md"
+    category: deprecated
 ```
 
-The command emits a config fragment rather than mutating policy automatically.
-This keeps the control plane reviewable while still avoiding hardcoded adapter
-branches.
+Profiles may classify paths and describe components. They cannot enable,
+disable, share, or unshare skills.
 
-When the fragment is acceptable, the same importer can merge it:
+## Import contract
 
 ```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --config skillboard.config.yaml \
-  --merge \
-  --dry-run
+skillboard import --profile <id-or-path> --source-root <dir> --out <fragment>
+skillboard import --profile <id-or-path> --source-root <dir> --config <path> --merge --dry-run
 ```
 
-Merge is append-only by default and refuses duplicate skill or install-unit ids.
-`--replace` is the explicit overwrite escape hatch. Drop `--dry-run` after
-reviewing the change plan.
-
-The reconciler then applies the same policy rules regardless of source.
+Import and inventory refresh create a missing valid v2 entry as
+`enabled: true`, `shared: false`, while preserving existing policy. Runtime and
+action permission remains with the agent or
+harness.
 
-## Default Safety
+This is a trust-neutral import: import does not review or approve a source and
+does not authorize any runtime component. Audit observations remain
+informational regardless of whether the fragment is only emitted or merged.
 
-New external skills should default to `vendor` or `candidate`, with
-`manual-only` or `router-only` invocation. Personal control skills can become
-`global-meta`, but external repositories should not gain `global-auto` through an
-adapter.
+Historical profile fields that encoded status, mode, exposure, or source review
+belong only to the v1 migration reader. New profiles must not emit them as
+availability policy.