superbee 0.1.1-pre.2 → 0.1.1

package/README.md

@@ -3,8 +3,9 @@
 **An OKF-native, CLI-first, agent-facing knowledge store.** Context notes, docs, cross-links,
 and live bundle Views — as a plain folder of user-owned files that works offline,
 with an optional wire backend when a separate service hosts the bundle. `superbee` is the
-[Superbee](https://github.com/Holaxis-ai/superbee) project's CLI. Its historical `aslite` and
-`agentstate-lite` commands remain supported aliases for existing installations.
+[Superbee](https://github.com/Holaxis-ai/superbee) project's CLI. Historical `aslite` and
+`agentstate-lite` invocations are recognized for migration, but the successor package installs
+only the canonical `superbee` command.
 
 The npm artifact ships one self-contained executable file with **zero runtime dependencies**,
 plus the generated Agent Skill (`SKILL.md` and its `references/` folder — installable into host
@@ -12,12 +13,11 @@ skill folders with `superbee skill install`). npm is the sole executable distrib
 the installed Skill contains guidance and references, not a second CLI copy. Maintainers can
 reproduce the complete package proof from the
 repository root with `npm run verify:npm-package`; it builds, packs, installs into an isolated
-prefix, resolves both command names from `PATH`, and exercises an offline bundle workflow. This
+prefix, proves that only `superbee` resolves from `PATH`, and exercises an offline bundle workflow. This
 developer proof deliberately stamps `local-dev`, so it works on an in-progress/dirty checkout;
 `prepublishOnly` runs the same journey in strict `npm-package` mode and refuses unless Git proves
 an exact clean source commit.
-Install the supported default once (`superbee` is canonical; the legacy aliases `aslite` and
-`agentstate-lite` remain supported), then complete host setup:
+Install the supported default once, then complete host setup:
 
 ```sh
 npm install -g superbee
@@ -35,10 +35,10 @@ Then run the first-value flow from an ordinary project directory:
 ```sh
 superbee
 superbee recipes
-superbee init --create-only --recipe work-tracking --dir .agentstate-lite
+superbee init --create-only --recipe work-tracking --dir .superbee
 superbee new "Task" first-task --title "Plan the first change" \
-  --progress_status todo --actor quickstart-agent --dir .agentstate-lite
-superbee --dir .agentstate-lite
+  --progress_status todo --actor quickstart-agent --dir .superbee
+superbee --dir .superbee
 ```
 
 `--create-only` fails before writing when the selected target is occupied or ambiguous. Use
@@ -52,6 +52,10 @@ Existing `.agentstate-lite/` bundles and `.agentstate.json` bindings need no mig
 read-only and bootstrap commands without installing anything, run `npx -y superbee`; persistent
 integrations still require the global npm install.
 
+The successor package can be installed while a global `@holaxis/aslite` still supplies the old
+commands. Run `superbee setup` to migrate exact legacy integrations, then remove the old package
+with `npm uninstall -g @holaxis/aslite` when setup is complete.
+
 If upgrading from the retired marketplace plugin, remove or disable that plugin, then rerun
 `superbee setup` and follow its exact next command. The hook installer
 replaces exact historical AgentState marketplace hooks instead of adding a duplicate.
@@ -99,4 +103,4 @@ Design and format docs live in the repository.
 
 ## License
 
-MIT © Holaxis
+Apache-2.0 © 2026 Holaxis

package/SKILL.md

@@ -12,8 +12,8 @@ description: >-
 
 read and write a local OKF knowledge bundle (context notes, docs, cross-links, live bundle Views).
 
-It is a standalone npm package (`superbee`) installing three bins for the identical CLI: `superbee` and the
-legacy aliases `aslite` and `agentstate-lite`. Every example below uses `superbee`.
+It is a standalone npm package (`superbee`) installing only the canonical `superbee` bin.
+Legacy `aslite` and `agentstate-lite` invocations are recognized only for migration.
 
 Output is TOON on stdout (a `--json` hatch exists). Errors are structured TOON on stdout with a
 capped exit-code taxonomy (0 ok/no-op, 2 usage, 4 auth, 5 conflict, 6 not-found, 1 runtime).
@@ -24,7 +24,7 @@ capped exit-code taxonomy (0 ok/no-op, 2 usage, 4 auth, 5 conflict, 6 not-found,
 
 Every example below assumes the `superbee` bin is on PATH. If it is not:
 
-- `npm install -g superbee` puts it (and the legacy aliases `aslite` and `agentstate-lite`) on PATH.
+- `npm install -g superbee` puts the canonical `superbee` command on PATH.
 - `npx -y superbee …` runs any command below with no install at all — swap the leading `superbee`
   for that prefix and the rest of the line runs unchanged.
 
@@ -38,11 +38,20 @@ superbee setup
 
 Without `--host`, setup returns the four supported host rows. Select the exact host running
 this agent, run that row's command, then follow the one `next.command` in each host-scoped
-plan, filling any explicit placeholder it identifies. Setup is read-only: it composes npm,
-Skill, Hook, MCP, bundle, and catalog status but never treats detection as permission to write.
+plan, filling any explicit placeholder it identifies. Bare and host-scoped setup are read-only: they compose npm,
+Skill, Hook, MCP, bundle, and catalog status but never treat detection as permission to write.
 Ask the human before running a returned mutating command. Restart the host after Skill, Hook,
 or MCP changes, then rerun the same setup command to verify. Foreign or unreadable state
 returns a read-only inspection command instead of overwriting it.
+If setup returns `superbee setup migrate-state`, that exact explicit command copies only
+validated private operational records into Superbee's canonical state root; it never moves
+bundles or deletes legacy bytes.
+
+A catalog entry preserves a workspace for explicit MCP selection; it never selects that
+workspace as the current project's context. Do not read, write, orient from, or sync a
+cataloged workspace merely because setup or a legacy MCP registration references it. Operate
+only on a bundle resolved from the current checkout or one the user explicitly selects. If
+the current checkout has no bundle, report that fact and stop bundle-oriented work.
 
 ## Stable MCP launch
 
@@ -64,52 +73,52 @@ Use `superbee mcp status --host <id>` to verify it and restart the host after a
   — Create (or open) an OKF knowledge bundle in a directory — greenfield setup; a project that already shares a board is set up by sync, not init. --create-only requires a genuinely NEW target and refuses existing, non-empty, symlinked, enclosing, bound, or concurrent targets before publication; runtime failures retain and report any empty directories they created instead of deleting them — 'recipe add' modifies a verified existing bundle
 - `superbee index generate [--dir <path>] [--check] [--force] [--actor <name>]`
   — Generate complete portable Markdown navigation explicitly; refuses curated indexes unless --force adopts them
-- `superbee status [--limit <n>] [--remote <url>]`
+- `superbee status [--limit <n>] [--dir <path>] [--remote <url>]`
   — Read-only bundle health report (kind lint, unresolved links, orphans, staleness, graph lints)
 
 ### Documents & links
 
-- `superbee doc write <id> --type <t> [--title <t>] [--body <s> | --body-file <p>] [--actor <n>] [--remote <url>]`
+- `superbee doc write <id> --type <t> [--title <t>] [--body <s> | --body-file <p>] [--actor <n>] [--dir <path>] [--remote <url>]`
   — Write a generic OKF concept document
-- `superbee doc update <id> [--<field> <value> ...] [--title <t>] [--tag <t>] [--type <t>] [--body <s> | --body-file <p>] [--expected-version <v>] [--actor <n>] [--remote <url>]`
+- `superbee doc update <id> [--<field> <value> ...] [--title <t>] [--tag <t>] [--type <t>] [--body <s> | --body-file <p>] [--expected-version <v>] [--actor <n>] [--dir <path>] [--remote <url>]`
   — Patch given fields (incl. kind-declared fields like --progress_status) of an existing doc, preserving the rest; optimistic-CAS with --expected-version
-- `superbee doc read <id> [--out (<path> | -) | --body-out (<path> | -) | --field <name>] [--remote <url>]`
+- `superbee doc read <id> [--out (<path> | -) | --body-out (<path> | -) | --field <name>] [--dir <path>] [--remote <url>]`
   — Read a doc, export its raw markdown, export its body with a same-read CAS version, or print one raw field for scripting
 - `superbee doc open <id> [--dir <path> | --remote <url>] [--port <n>] [--actor <name>]`
   — Open one exact authoritative document in the existing rendered browser UI
-- `superbee doc history <id> [--limit <n>] [--remote <url>]`
+- `superbee doc history <id> [--limit <n>] [--dir <path>] [--remote <url>]`
   — Show a doc's version history (newest first, capped at 20 by default — --limit 0 for all; a history-keeping backend returns the full attributed chain, a local bundle just the current revision) — the tokens for --expected-version
-- `superbee doc delete <id> [--expected-version <v>] [--remote <url>]`
+- `superbee doc delete <id> [--expected-version <v>] [--dir <path>] [--remote <url>]`
   — Hard-delete a doc (idempotent: absent -> deleted:false, exit 0)
-- `superbee list [--type <t>] [--tag <t>] [--field <k=v>] [--prefix <p>] [--open] [--limit <n>] [--remote <url>]`
+- `superbee list [--type <t>] [--tag <t>] [--field <k=v>] [--prefix <p>] [--open] [--limit <n>] [--dir <path>] [--remote <url>]`
   — Query concepts over their frontmatter (alias: query) — a comma in --field's value is set membership (OR); --open excludes terminal instances (declared kinds only)
-- `superbee link (add <from> <to> [--text <t>] [--actor <n>] | show <id> [--limit <n>] [--text <t>] | list [--from <id|prefix/>] [--to <id|prefix/>] [--text <t>] [--limit <n>]) [--remote <url>]`
+- `superbee link (add <from> <to> [--text <t>] [--actor <n>] | show <id> [--limit <n>] [--text <t>] | list [--from <id|prefix/>] [--to <id|prefix/>] [--text <t>] [--limit <n>]) [--dir <path>] [--remote <url>]`
   — Add a cross-link, show a concept's links + backlinks, or query the whole bundle's derived edge list filtered by from/to (id or prefix/, repeatable/union) and exact-match text
 
 ### Artifacts
 
-- `superbee artifact create <file> --title <title> [--description <text>] [--supersedes <id>] [--actor <n>] [--remote <url>]`
+- `superbee artifact create <file> --title <title> [--description <text>] [--supersedes <id>] [--actor <n>] [--dir <path>] [--remote <url>]`
   — Produce a shareable output (HTML) a human can view: one command promotes the bytes and writes the type:Artifact record
-- `superbee promote <file> --doc-key <key> [--content-type <mime>] [--expected-version <v>] [--remote <url>]`
+- `superbee promote <file> --doc-key <key> [--content-type <mime>] [--expected-version <v>] [--dir <path>] [--remote <url>]`
   — Move a local file's bytes into the store (a .md key routes through the engine; else a blob)
-- `superbee pull --doc-key <key> --out (<path> | -) [--remote <url>]`
+- `superbee pull --doc-key <key> --out (<path> | -) [--dir <path>] [--remote <url>]`
   — Pull a doc's canonical form or a blob's raw bytes out of the store (the reverse of promote)
-- `superbee blobs [--prefix <p>] [--limit <n>] [--remote <url>]`
+- `superbee blobs [--prefix <p>] [--limit <n>] [--dir <path>] [--remote <url>]`
   — List the store's blob (non-document) keys (documents are listed by 'list'/'query')
-- `superbee delete --doc-key <key> [--expected-version <v>] [--remote <url>]`
+- `superbee delete --doc-key <key> [--expected-version <v>] [--dir <path>] [--remote <url>]`
   — Hard-delete a doc or blob by key (idempotent: absent -> deleted:false, exit 0)
 
 ### Kinds
 
-- `superbee new "<Kind>" <id> --<field> <value> [...] [--body <markdown> | --body-file <path>] [--link "<type>=<target-id>" ...] [--no-prefix] [--actor <n>] [--remote <url>]`
+- `superbee new "<Kind>" <id> --<field> <value> [...] [--body <markdown> | --body-file <path>] [--link "<type>=<target-id>" ...] [--no-prefix] [--actor <n>] [--dir <path>] [--remote <url>]`
   — Create a new instance of a bundle-declared kind — initial Markdown may come from --body or --body-file (otherwise declared sections are scaffolded); validates strictly, and repeatable --link wires typed cross-links in the same step
-- `superbee kinds [--remote <url>]`
+- `superbee kinds [--dir <path>] [--remote <url>]`
   — List the kind conventions this bundle declares (purpose, described fields, exact required body headings, typed-link vocabulary, horizon)
-- `superbee kind field "<Kind>" (add <name> [--required] [--values <a,b,c>] | remove <name>) [--remote <url>]`
+- `superbee kind field "<Kind>" (add <name> [--required] [--values <a,b,c>] | remove <name>) [--dir <path>] [--remote <url>]`
   — Edit a kind's schema — add/remove a declared field or enum value on its convention (idempotent)
 - `superbee recipes [--dir <path>] [--remote <url>]`
   — Browse built-in recipes before or after init; with a bundle, also show whether each is already applied
-- `superbee recipe add <name-or-path> [--remote <url>]`
+- `superbee recipe add <name-or-path> [--dir <path>] [--remote <url>]`
   — Apply a recipe's content-free definitions — Kinds plus optional declared References and Views — idempotently
 
 ### Remote
@@ -135,12 +144,12 @@ Use `superbee mcp status --host <id>` to verify it and restart the host after a
   — Install the SessionStart hook (runs session-start: pull the board, then render) for Claude Code, Codex, OpenCode
 - `superbee skill install|status|uninstall [--scope project|user]`
   — Install this package's Agent Skill (SKILL.md + references/) into Claude Code and Codex skill folders (OpenCode has no skill surface — its integration is `hook install`); manifest-tracked, idempotent, refuses folders it does not manage
-- `superbee setup [--host codex|claude-code|claude-desktop|opencode] [--scope project|user] [--json]`
-  — Inspect npm, Skill, Hook, MCP, bundle, and catalog readiness, then emit one deterministic safe next command
+- `superbee setup [migrate-state] [--host codex|claude-code|claude-desktop|opencode] [--scope project|user] [--json]`
+  — Inspect npm, private state, Skill, Hook, MCP, bundle, and catalog readiness, then emit one deterministic safe next command
 
-## Workspaces — the project's bundle lives at `.agentstate-lite/` in the project root
+## Workspaces — the project's bundle lives at `.superbee/` in the project root
 
-Unless the user directs otherwise, a project's workspace bundle lives in a `.agentstate-lite/`
+Unless the user directs otherwise, a project's workspace bundle lives in a `.superbee/`
 folder at the project root. Two verbs, two different jobs — `init` always creates a LOCAL
 bundle (solo use is first-class, nothing forces sharing); `sync` is how a project's board
 becomes — or stays — shared memory across clones and teammates. Three modes:
@@ -151,7 +160,7 @@ becomes — or stays — shared memory across clones and teammates. Three modes:
   `sync` on a local-only bundle reports that state honestly (its note points at `--establish`)
   — it never establishes on its own, which would silently publish a bundle nobody asked to
   share.
-- **Joining an existing shared board** — if `.agentstate-lite/` is already in the clone, there
+- **Joining an existing shared board** — if `.superbee/` or a legacy `.agentstate-lite/` is already in the clone, there
   is NOTHING to set up. If it isn't but the project already shares its board (the repo's
   remote has a `board` branch), `sync` is the setup verb — run it once and it creates the
   folder and pulls the shared state. NEVER init a project that already has a workspace: that
@@ -167,7 +176,7 @@ becomes — or stays — shared memory across clones and teammates. Three modes:
 
 ```sh
 superbee sync                            # existing shared project — provisions the board; a local-only bundle reports its state
-superbee init --dir .agentstate-lite     # greenfield — idempotent; creates a LOCAL bundle, or opens an existing one
+superbee init --create-only --dir .superbee  # greenfield — creates one genuinely new LOCAL bundle
 superbee sync --establish                # establish a new shared board after user approval
 ```
 
@@ -211,7 +220,8 @@ Otherwise bundle resolution stays local: explicit `--dir` → nearest `.superbee
 supported `.agentstate.json` local-path binding up-tree → the cwd walk, which at each
 ancestor checks both binding names together (both at one level fail closed), then the
 directory's own `index.md`, then its
-conventional `.agentstate-lite/index.md`. Reserve `--dir` for the exceptions: a bundle outside
+conventional `.superbee/index.md` or legacy `.agentstate-lite/index.md`. Reserve `--dir` for the exceptions: a bundle outside
+If both conventional directories contain valid bundles at one project level, discovery refuses with a conflict; move the bundle you do not intend to use outside the project before retrying.
 any project, a second workspace, or reaching another project's bundle from elsewhere.
 
 Two things override the default:
@@ -226,7 +236,7 @@ Two things override the default:
    it rather than creating a second one.
 
 If the user wants the workspace PRIVATE to their machine instead of shared (a personal
-scratch workspace), keep the bundle OUT of the repo (e.g. under `~/.agentstate/<name>/`)
+scratch workspace), keep the bundle OUT of the repo (e.g. under `~/superbee-workspaces/<name>/`)
 and point a git-excluded `.superbee.json` at it. Choose by one question: do teammates
 share this bundle? When the user's intent is ambiguous, ask rather than defaulting silently.
 
@@ -242,7 +252,7 @@ the tradeoff and record that explicit choice; never silently substitute one for
 ```sh
 # One-time setup at the project root (see the Workspaces section) — run ONE of these:
 superbee sync                          # existing project that shares a board — sets up AND pulls the shared board
-superbee init --dir .agentstate-lite   # GREENFIELD — never on a project that already has a workspace; makes a LOCAL bundle
+superbee init --create-only --dir .superbee  # GREENFIELD — never on a project that already has a workspace; makes a LOCAL bundle
 
 # If collaboration is requested, offer the explicit one-time shared-board operation:
 superbee sync --establish
@@ -274,7 +284,9 @@ while leaving code-project files untouched.
 
 On a shared board, run it whenever you close a unit of work — a task finished, a decision recorded, a session
 ending. Local-only work remains complete locally. Three known empty states (all exit 0):
-outside any git repo or workspace it prints `sync: nothing to sync`; a LOCAL-ONLY board (a
+in an ordinary directory outside any git repo or workspace it prints `sync: nothing to sync`
+(inside Superbee's private user-state root it refuses — that is a conflict, not an empty
+state); a LOCAL-ONLY board (a
 bundle with no shared `board` branch — a supported mode) reports itself as local-only, with
 nothing committed, pulled, or pushed, and its note points at `--establish` — but bare `sync`
 NEVER establishes on its own (that would silently publish a bundle nobody asked to share);