agent-skillboard 0.2.18 → 0.3.1

package/docs/routing.md

@@ -1,100 +1,33 @@
-# Capability Routing
+# Routing
 
-Capability routing helps an AI choose a skill for the user's current request
-without making the user learn SkillBoard commands.
+Routing chooses among skills already available to the current agent. Guard
+decides availability from valid generated inventory, `enabled`, and
+`installed_on`; routing cannot override that verdict.
 
-SkillBoard is intentionally permissive at this layer: workflow-bound skills can
-remain broadly available, and routing only chooses the skill that should steer
-this request. When several allowed skills match, the response includes
-`overlap_resolution` so the AI can explain that the other skills stayed
-available while the workflow routed to one selected skill.
+## Resolution order
 
-For the normal AI-mediated flow, prefer `brief --intent`. It returns the
-availability brief and the routing result together:
+1. Remove skills missing valid inventory records.
+2. Remove disabled skills.
+3. Remove skills not installed for the selected agent.
+4. Honor an explicit user-selected skill if it remains eligible.
+5. Rank intent matches by optional preference and priority.
+6. Return one recommendation and ordered fallbacks.
 
-```bash
-skillboard brief \
-  --intent "write tests before implementation" \
-  --workflow codex-night-workflow \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --json
-```
-
-Read `assistant_guidance.route` from the JSON output. It includes:
-
-- `matched_capability`
-- `match_source`
-- `confidence`
-- `matched_terms`
-- `recommendation_reason`
-- `recommended_skill`
-- `fallback_skills`
-- `route_candidates`
-- `overlap_resolution`
-- `policy_memory`
-- `post_use_policy_suggestion`
-- `guard_command`
-- `usage_disclosure`
-
-When `guard_allowed` is true, the AI should run the guard automatically before
-using the skill. It should not ask for another approval. It should disclose the
-skill at the start and at completion:
-
-```text
-I will use <skill-id> for this request.
-I used <skill-id> for this request.
-```
-
-When several skills match, inspect `route_candidates` before acting. Each entry
-shows the candidate skill, whether it was selected, whether the guard currently
-allows it, and the guard reason when it is denied. This is the field that tells
-an AI why a preferred skill was skipped and an allowed fallback was selected.
-Inspect `overlap_resolution` first when it is present: `status: resolved` with
-`mode: permissive-routing` means multiple allowed skills matched, SkillBoard
-kept them available, and the current workflow still has one deterministic route.
-When `policy_memory` is present, remembered or configured workflow policy
-selected the routed skill while other allowed skills were also available. The AI
-should mention that after completion so the user knows a stored policy
-preference shaped the route.
-
-When routing is safe but policy learning would reduce future ambiguity,
-SkillBoard may return `post_use_policy_suggestion`. This includes cases where a
-preferred skill is denied and an allowed fallback is selected, or where multiple
-allowed workflow-bound skills match and one allowed skill is selected
-deterministically. The AI should keep the task moving with the allowed routed
-skill, then ask after completion whether to remember that skill as the preferred
-workflow policy. The suggested policy command is informational until the user
-confirms it.
-
-Use `route` directly when an automation layer only needs the recommendation
-payload:
+Preference ranks only and never changes availability.
 
 ```bash
-skillboard route "write tests before implementation" \
-  --workflow codex-night-workflow \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --json
+skillboard brief --intent "write tests" --agent codex --json
+skillboard route "write tests" --agent codex --json
+skillboard guard use test-first --agent codex --json
 ```
 
-Routing first matches declared workflow capabilities. If the workflow has skill
-bindings but no matching capability, it can fall back to workflow-bound skill
-metadata such as id, path, category, `SKILL.md` name, and `SKILL.md`
-description.
-
-Routing does not invoke the skill. The final boundary is still:
-
-```bash
-skillboard guard use <skill-id> \
-  --workflow codex-night-workflow \
-  --config skillboard.config.yaml \
-  --skills skills
-```
+These commands use `~/skillboard.config.yaml` and
+`~/.skillboard/inventory.json` from any working directory. Advanced
+`--config` and `--skills` overrides remain available for migration, testing,
+and legacy workspaces.
 
-If no capability or workflow-bound skill matches, SkillBoard returns
-`recommended_skill: null`. Ask a clarifying question before choosing a skill.
+When guard allows use, continue without another approval. Ask after completion
+only when remembering a preference would reduce future ambiguity.
 
-See [Value proof](value-proof.md) for an executable route example that selects
-`matt.tdd`, returns `private.tdd-work-continuity` as fallback, and verifies the
-guard and disclosure fields.
+Source and provenance findings are optional audit metadata and never determine
+availability. Runtime and action authorization are outside SkillBoard's scope.

package/docs/user-flow.md

@@ -1,325 +1,114 @@
-# First-Time Skill Control Flow
+# User Flow
 
-This flow assumes a user installed SkillBoard so their AI can keep installed
-skills broadly available while resolving confusing overlap only when it matters.
+SkillBoard is a user-level control plane, not a per-project setup step. Users
+enable or disable skills and may opt individual skills into cross-agent sharing.
+Installed skills default to enabled and agent-local.
 
-When you ask your AI normal work requests such as "write tests before
-implementation", "review this plan and point out weak assumptions", or "help me
-refine this UX flow," the AI should work normally. SkillBoard becomes relevant
-when skill choice is ambiguous, several skills overlap, workflow priority
-matters, or you explicitly ask for a SkillBoard or skill decision such as "what
-skills can you use here?" or "make this reviewed skill available for this
-workflow." In those cases, the AI should read the current brief, show the
-relevant choice, ask only before applying one current action id when policy
-would change, and run the final guard automatically before invocation. For an
-already-allowed skill, the AI should state which skill it is about to use and
-which skill it used when reporting the result, not ask for another approval.
-That disclosure is an audit trace, not a permission prompt. If you explicitly
-ask for a specific already-allowed skill, the AI should honor that request after
-guard use instead of rerouting away solely because another skill also matches.
-You do not need to memorize the SkillBoard command loop. The command examples
-below are AI/automation/operator details for the agent, scripts, or people
-maintaining the setup.
-
-If you ask OpenCode to use a skill you previously used in Codex, the target
-agent should call:
+## 1. Install and ask normally
 
 ```bash
-skillboard import-skill --from codex --to opencode --skill <skill> --json
+npm install -g agent-skillboard
 ```
 
-Compatible skills are installed into the target agent's user skill root. When
-the source is agent-specific, the agent should explain the compatibility issue
-and ask before producing a target-agent adapted `SKILL.md`.
-
-Before changing this routing or workflow UX, read
-[`docs/ai-skill-routing-goal.md`](ai-skill-routing-goal.md). The goal is to keep
-SkillBoard non-blocking: observe the request, route to the current best skill,
-work normally, explain briefly, ask after use only when a policy preference would
-help, and remember that usage policy without rewriting skill bodies.
-
-## 1. Start From Agent-Layer Setup
-
-AI/automation/operator details:
+Postinstall creates `~/skillboard.config.yaml`, refreshes
+`~/.skillboard/inventory.json`, and installs managed guidance for detected
+agents. No project init is needed. If setup was skipped:
 
 ```bash
-skillboard setup --agent codex,claude,opencode,hermes --yes
+skillboard setup --yes --agent codex
 ```
 
-Package install and `skillboard setup` write user-agent guidance only. They do
-not create `skillboard.config.yaml`, `.skillboard/`, `AGENTS.md`, or
-`CLAUDE.md` in projects. `skillboard init` is deprecated project-local policy
-bootstrap and is not needed for normal use; use it only when maintaining an
-existing workspace that intentionally keeps local SkillBoard policy files. Use
-`skillboard doctor --strict` only for an existing policy workspace when
-review-needed safe-mode warnings should fail automation.
-
-When the user asks the agent what it can use, the agent should read the current
-brief with `skillboard brief --json` first and answer from the brief rather than
-reading skill files directly. The user-facing text output uses sections such as
-"What your AI can use now", "Needs your decision", and "Blocked for safety";
-text briefs include previewable action cards by default, while the JSON form
-keeps action cards opt-in. For large skill sets, the default text brief stays
-compact: counts, top categories, next safe action, short previews per section,
-and short action summaries. Use `skillboard brief --verbose` when an operator
-needs every skill and full copyable command details. Those action cards are
-suggestions only: the agent should pick one current action id from the brief,
-request confirmation before applying risk-bearing changes, then run
-`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json`
-with `--workflow <name>` when a workflow is selected. The agent should read the
-returned post-apply brief before making the next availability claim.
-`apply-action` re-resolves the current brief and refuses stale action ids instead
-of replaying cached action-card shell text.
-
-When a normal request leaves skill choice ambiguous, several skills overlap,
-workflow priority matters, or the user asks for a SkillBoard or skill decision,
-the agent can keep the same brief flow and include the user request as intent:
+If an agent is installed later, rerun the same command for that agent. Setup
+discovers standard homes and Hermes profiles, installs guidance, refreshes
+inventory, and backfills only skills the user already selected with
+`shared: true`. For a custom location:
 
 ```bash
-skillboard brief --intent "write tests before implementation" --workflow daily-workflow --config skillboard.config.yaml --skills skills --json
+skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes
 ```
 
-The returned `assistant_guidance.route` maps the request to a declared workflow
-capability or a workflow-bound skill metadata match, returns the recommended
-skill and fallbacks, and includes `match_source`, `matched_terms`,
-`recommendation_reason`, `route_candidates`, `overlap_resolution`,
-`policy_memory`,
-`post_use_policy_suggestion`, and the `skillboard guard use ...` command that
-still needs to pass immediately before invocation. `overlap_resolution`
-summarizes permissive routing when several allowed skills match.
-`route_candidates` is the per-skill decision trace: it shows which matching
-skill was selected, which candidates were denied, and the guard reason when a
-preferred skill was skipped for an allowed fallback.
-`policy_memory` appears when remembered or configured workflow policy selected
-the routed skill while other allowed skills were also available; the agent
-should mention that after completion so the user understands the prior choice
-shaped the route.
-`post_use_policy_suggestion` is the ask-after-use hook: if it is present, the
-agent should use the allowed routed skill first, then ask after completion
-whether to remember the suggested preference. Metadata matching can
-use declared skill id, path, category, and `SKILL.md` frontmatter
-name/description; it does not semantically rank raw skill bodies. If a
-recommended skill is already allowed, the agent should disclose it at the start
-and completion rather than ask for another approval. If the user explicitly
-requests a specific already-allowed skill, the agent should honor that request
-after guard use instead of rerouting away solely because another skill also
-matches. If no capability or workflow-bound skill matches, the agent should ask
-a clarifying question instead of guessing from raw `SKILL.md` text. Operators can still call
-`skillboard route ...` directly when they only need the recommendation payload.
+The registered root survives later setup and package-update runs. No project
+init, profile-specific policy layer, or new approval per already-shared skill is
+introduced. Unmanaged collisions are preserved and reported.
 
-Run this again after installing agent packages, plugins, workflow bundles, or
-harnesses:
-
-```bash
-skillboard inventory refresh --dry-run
-skillboard inventory refresh
-```
-
-## 2. Add A User-Owned Skill
-
-AI/automation/operator details:
-
-Create the skill under the project `skills/` directory:
-
-```bash
-mkdir -p skills/user-helper
-$EDITOR skills/user-helper/SKILL.md
-```
+## 2. Observe and route
 
-Register it without making it callable yet:
+From any directory, the agent reads:
 
 ```bash
-skillboard add skill user.helper \
-  --path user-helper \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --dry-run
-
-skillboard add skill user.helper \
-  --path user-helper \
-  --config skillboard.config.yaml \
-  --skills skills
+skillboard brief --intent "<request>" --agent codex --json
+skillboard guard use <skill-id> --agent codex --json
 ```
 
-The dry run reports semantic YAML changes and leaves the config untouched. The
-real command adds the skill as a direct user-owned `candidate` by default.
+The guard allows an enabled skill only when generated inventory records it on
+the selected agent. Preference ranks matching candidates and never changes
+availability. Allowed use does not require another confirmation.
 
-Create a workflow or harness for the skill without hand-editing YAML:
+## 3. Change one decision
 
 ```bash
-skillboard add harness codex \
-  --config skillboard.config.yaml \
-  --skills skills
-
-skillboard add workflow daily-workflow \
-  --harness codex \
-  --skill user.helper \
-  --config skillboard.config.yaml \
-  --skills skills
+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>
 ```
 
-When `add workflow` attaches a `candidate` / `manual-only` skill, it promotes the
-skill to `active` with `invocation: manual-only` for that workflow. It still
-does not grant automatic model invocation.
-
-## 3. Inspect Influence Before Use
+Share copies the complete skill directory to SkillBoard's managed shared source
+and compatible agent roots while preserving the owner copy. Unshare removes only
+copies managed by SkillBoard. It never deletes agent-owned originals.
 
-AI/automation/operator details:
+For AI mediation, read `brief --include-actions --json`, confirm one current
+action, run `skillboard apply-action <action-id> --agent <agent> --yes --json`, and reread the
+returned post-apply brief. Cached action ids are not reused.
 
-```bash
-skillboard explain user.helper \
-  --config skillboard.config.yaml \
-  --skills skills
+## 4. Ask after, then remember
 
-skillboard can-use user.helper \
-  --workflow daily-workflow \
-  --config skillboard.config.yaml \
-  --skills skills
+When a route was ambiguous, the agent finishes first. It may then ask whether to
+remember an intent preference. Preference affects ordering only; it does not
+share, enable, disable, install, or remove a skill.
 
-skillboard impact disable user.helper \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --out .skillboard/reports/user-helper-impact.md
-```
+## 5. Audit separately
 
-`explain` shows source class, trust, owner install unit, workflow roles, and
-capability roles. `can-use` is the machine-readable gate for agents. `impact`
-shows which workflows and required outputs would be affected before disabling or
-removing a skill.
+Source and provenance are optional audit metadata and never determine
+availability. Import is trust-neutral: valid discoveries default to enabled and
+agent-local. Runtime and action authorization are outside SkillBoard's scope and
+remain with the agent or harness.
 
-For an actual invocation, `brief` is not the final permission check. Agents
-should run `skillboard guard use ...` automatically immediately before calling a
-skill so state changes made after the brief cannot slip through. A passing guard
-does not require another user prompt; the agent should disclose the skill use at
-the start and in the final result. That disclosure is an audit trace, not a
-permission prompt.
+## 6. Remove a skill cleanly
 
-When wiring a guard hook from an action card, keep `apply-action` as the
-action-card primary flow:
+Remove the original skill with the agent, plugin, or package manager that owns
+it. Then refresh observations and remove only its stale SkillBoard policy:
 
 ```bash
-skillboard apply-action <action-id> --workflow daily-workflow --config skillboard.config.yaml --skills skills --yes --json
-```
-
-The raw hook commands are underlying manual operator detail for previewing and
-materializing an executable guard hook outside the action-card control loop:
-
-```bash
-skillboard hook install --workflow daily-workflow --config skillboard.config.yaml --skills skills --out .skillboard/hooks/daily-workflow-guard.sh --dry-run --json
-skillboard hook install --workflow daily-workflow --config skillboard.config.yaml --skills skills --out .skillboard/hooks/daily-workflow-guard.sh
-```
-
-For direct manual hook installation, inspect the JSON `planned.preview.shell`
-before an operator materializes the matching non-dry-run hook command. Generated
-hooks pin the install-time SkillBoard command, config, skills root, and workflow;
-set those values with hook install options such as `--skillboard-bin`, not with
-runtime environment overrides.
-
-## 4. Enable, Disable, Or Prefer
-
-AI/automation/operator details:
-
-Enable the skill only for the workflow that should see it:
-
-```bash
-skillboard activate user.helper \
-  --workflow daily-workflow \
-  --config skillboard.config.yaml \
-  --skills skills
-```
-
-If you already used `skillboard add workflow ... --skill user.helper`, this
-manual activation step is not needed for direct user invocation.
-
-Block it from a workflow without deleting the declaration or file:
-
-```bash
-skillboard block user.helper \
-  --workflow daily-workflow \
-  --config skillboard.config.yaml \
-  --skills skills
-```
-
-Prefer it for a capability when the workflow should depend on a role rather than
-a raw skill id:
-
-```bash
-skillboard prefer user.helper \
-  --workflow daily-workflow \
-  --capability task-review \
-  --config skillboard.config.yaml \
-  --skills skills
-```
-
-## 5. Remove Governance Without Deleting User Files
-
-AI/automation/operator details:
-
-First try the safe remove:
-
-```bash
-skillboard remove skill user.helper \
-  --config skillboard.config.yaml \
-  --skills skills
-```
-
-If workflows, capabilities, or install units still reference the skill, the
-command refuses to remove it and prints the references. After reviewing the
-impact, remove the config declaration and references:
-
-```bash
-skillboard remove skill user.helper \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --force \
-  --dry-run
-
-skillboard remove skill user.helper \
-  --config skillboard.config.yaml \
-  --skills skills \
-  --force
+skillboard inventory refresh
+skillboard skill forget <skill-id> --dry-run
+skillboard skill forget <skill-id>
 ```
 
-This removes SkillBoard policy references only and leaves
-`skills/user-helper/SKILL.md` in place.
-
-## 6. Stop Using SkillBoard Safely
-
-AI/automation/operator details:
-
-Remove managed user-agent guidance first if global install/setup made agents
-recognize SkillBoard and you want that agent-layer footprint gone:
-
-```bash
-skillboard uninstall --agent-layer --dry-run
-skillboard uninstall --agent-layer
-```
+Forget refuses a skill that is still observed or has `shared: true`. Unshare it
+before removing the owner copy. Forget never deletes a `SKILL.md` or directory.
 
-This removes only managed `skillboard/SKILL.md` guidance files containing the
-SkillBoard agent integration marker. It preserves other agent skills and
-user-authored `skillboard` skills.
+## 7. Uninstall SkillBoard cleanly
 
 ```bash
-skillboard uninstall --dry-run
-skillboard uninstall
+skillboard uninstall --user --dry-run
+skillboard uninstall --user --yes
+npm uninstall -g agent-skillboard
 ```
 
-Uninstall removes generated bridge blocks and unchanged helper files. It
-also removes `skillboard.config.yaml` and the `.skillboard/` project state by
-default while preserving local `skills/` files and user-authored non-SkillBoard
-content in bridge files.
+The preview lists every marker-owned shared copy, managed guidance file, and
+home state path. Apply requires `--yes`, preserves agent-owned and unmanaged
+skills, and does not touch project files.
 
-If you want to keep project SkillBoard policy and bridge guidance, opt into
-settings preservation explicitly:
+## 8. Migrate version 1
 
 ```bash
-skillboard uninstall --keep-settings --dry-run
-skillboard uninstall --keep-settings
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-`--purge` is still accepted as an explicit spelling for the default clean
-project removal. Default removal and `--purge` both discard the current
-SkillBoard config even if it contains imported skills or workflow edits, remove
-generated dashboard and impact reports, and remove the entire `.skillboard/`
-project state directory, including hooks, source caches, rollout logs, variant
-snapshots, and profiles. Local `skills/` files stay in place.
+Version 1 remains readable but immutable for the v0.3.x one-release read-only
+window. v0.4.0 removes the v1 reader. No ordinary command migrates implicitly.