ctxbin 0.1.0 → 0.1.1

package/README.md

@@ -13,11 +13,11 @@ so agents consistently save and load branch context.
 - Add: [`agent-addon.md`](agent-addon.md) → copy the block into your project's agent instruction file
   (e.g. `AGENT.md`, `CLAUDE.md`, or any equivalent).
 - Then you can simply ask:
-  - “Use ctxbin to save the current context.”
-  - “Use ctxbin to load the current context.”
+  - “Use npx ctxbin to save the current context.”
+  - “Use npx ctxbin to load the current context.”
 
 The add-on tells agents how to format context (summary, next steps, decisions) and how to use
-`ctxbin ctx save/load` correctly.
+`npx ctxbin ctx save/load` correctly.
 
 ## Features
 - Branch-scoped `ctx` keys (auto-inferred from git repo + branch)
@@ -58,10 +58,10 @@ npx ctxbin init
 ## Quick usage
 ### ctx (branch-scoped, key optional in git repos)
 ```bash
-ctxbin ctx save --value "summary / next steps"
-ctxbin ctx load
-ctxbin ctx list
-ctxbin ctx delete
+npx ctxbin ctx save --value "summary / next steps"
+npx ctxbin ctx load
+npx ctxbin ctx list
+npx ctxbin ctx delete
 ```
 
 When the key is omitted, ctxbin infers it **only inside a git repository**:
@@ -73,42 +73,42 @@ branch  = git rev-parse --abbrev-ref HEAD
 
 Explicit key example (useful outside git repos; not recommended for normal use):
 ```bash
-ctxbin ctx save my-project/main --value "summary / next steps"
-ctxbin ctx load my-project/main
-ctxbin ctx delete my-project/main
+npx ctxbin ctx save my-project/main --value "summary / next steps"
+npx ctxbin ctx load my-project/main
+npx ctxbin ctx delete my-project/main
 ```
 
 ### agent (string-only)
 ```bash
-ctxbin agent save reviewer --value "# Agent role"
-ctxbin agent load reviewer
-ctxbin agent list
-ctxbin agent delete reviewer
+npx ctxbin agent save reviewer --value "# Agent role"
+npx ctxbin agent load reviewer
+npx ctxbin agent list
+npx ctxbin agent delete reviewer
 ```
 
 ### skill (string, skillpack, or skillref)
 ```bash
-ctxbin skill save my-skill --value "# Skill markdown"
-ctxbin skill load my-skill
-ctxbin skill list
-ctxbin skill delete my-skill
+npx ctxbin skill save my-skill --value "# Skill markdown"
+npx ctxbin skill load my-skill
+npx ctxbin skill list
+npx ctxbin skill delete my-skill
 ```
 
 Skillpack (directory bundle):
 ```bash
-ctxbin skill save fp-pack --dir ./skills/fp-pack
-ctxbin skill load fp-pack --dir ./tmp/fp-pack
+npx ctxbin skill save fp-pack --dir ./skills/fp-pack
+npx ctxbin skill load fp-pack --dir ./tmp/fp-pack
 ```
 
 Skillref (GitHub directory reference):
 ```bash
 # Track default branch
-ctxbin skill save fp-pack \
+npx ctxbin skill save fp-pack \
   --url https://github.com/OWNER/REPO \
   --path skills/fp-pack
 
 # Pin to a commit
-ctxbin skill save fp-pack \
+npx ctxbin skill save fp-pack \
   --url https://github.com/OWNER/REPO \
   --ref <40-hex-commit-sha> \
   --path skills/fp-pack

package/agent-addon.md

@@ -6,7 +6,8 @@ Copy/paste the block between the markers below into your AGENT.md / CLAUDE.md.
 
 ## ctxbin (Context Persistence)
 
-Use `ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
+Use `npx ctxbin ...` when running commands in agent workflows.
+Use `npx ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
 > Tip: `npx ctxbin skill load ctxbin` prints the bundled ctxbin skill text
 > so agents can reference the full ctxbin guidance.
 
@@ -19,17 +20,17 @@ branch  = git rev-parse --abbrev-ref HEAD
 
 ### Save context (preferred)
 ```bash
-ctxbin ctx save --value "<summary + next steps + decisions>"
+npx ctxbin ctx save --value "<summary + next steps + decisions>"
 ```
 
 ### Save via stdin
 ```bash
-echo "<context>" | ctxbin ctx save
+echo "<context>" | npx ctxbin ctx save
 ```
 
 ### Load context
 ```bash
-ctxbin ctx load
+npx ctxbin ctx load
 ```
 
 ### What to include in ctx

package/dist/agent-addon.md

@@ -6,7 +6,8 @@ Copy/paste the block between the markers below into your AGENT.md / CLAUDE.md.
 
 ## ctxbin (Context Persistence)
 
-Use `ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
+Use `npx ctxbin ...` when running commands in agent workflows.
+Use `npx ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
 > Tip: `npx ctxbin skill load ctxbin` prints the bundled ctxbin skill text
 > so agents can reference the full ctxbin guidance.
 
@@ -19,17 +20,17 @@ branch  = git rev-parse --abbrev-ref HEAD
 
 ### Save context (preferred)
 ```bash
-ctxbin ctx save --value "<summary + next steps + decisions>"
+npx ctxbin ctx save --value "<summary + next steps + decisions>"
 ```
 
 ### Save via stdin
 ```bash
-echo "<context>" | ctxbin ctx save
+echo "<context>" | npx ctxbin ctx save
 ```
 
 ### Load context
 ```bash
-ctxbin ctx load
+npx ctxbin ctx load
 ```
 
 ### What to include in ctx

package/dist/skills/ctxbin/SKILL.md

@@ -3,7 +3,7 @@ name: ctxbin
 description: Use when working with ctxbin to save and load ctx, agent, and skill context.
 metadata:
   short-description: ctxbin workflow
-  version: 0.1.0
+  version: 0.1.1
 ---
 
 # ctxbin Skill
@@ -13,6 +13,7 @@ Help agents preserve and restore **branch-scoped project context** so the next a
 
 ## Core Usage (ctx)
 `ctx` automatically derives a key from the current Git repo and branch when omitted.
+Prefer `npx ctxbin ...` when running commands in agent workflows.
 
 ```
 key = {project}/{branch}
@@ -22,54 +23,54 @@ branch  = git rev-parse --abbrev-ref HEAD
 
 ### Save (most common)
 ```bash
-ctxbin ctx save --value "summary / next steps / notes"
+npx ctxbin ctx save --value "summary / next steps / notes"
 ```
 Or via stdin:
 ```bash
-echo "summary" | ctxbin ctx save
+echo "summary" | npx ctxbin ctx save
 ```
 
 ### Load
 ```bash
-ctxbin ctx load
+npx ctxbin ctx load
 ```
 
 ### List
 ```bash
-ctxbin ctx list
+npx ctxbin ctx list
 ```
 
 ### Delete
 ```bash
-ctxbin ctx delete
+npx ctxbin ctx delete
 ```
 
 ## agent Save/Load
 `agent` requires a key and stores **string values only**.
 
 ```bash
-ctxbin agent save reviewer --value "# Agent role"
-ctxbin agent load reviewer
+npx ctxbin agent save reviewer --value "# Agent role"
+npx ctxbin agent load reviewer
 ```
 
 ### List/Delete
 ```bash
-ctxbin agent list
-ctxbin agent delete reviewer
+npx ctxbin agent list
+npx ctxbin agent delete reviewer
 ```
 
 ## skill Save/Load
 `skill` requires a key.
 
 ```bash
-ctxbin skill save my-skill --value "# Skill markdown"
-ctxbin skill load my-skill
+npx ctxbin skill save my-skill --value "# Skill markdown"
+npx ctxbin skill load my-skill
 ```
 
 ### List/Delete
 ```bash
-ctxbin skill list
-ctxbin skill delete my-skill
+npx ctxbin skill list
+npx ctxbin skill delete my-skill
 ```
 
 ## Input Options (`--file`, `--value`, `--dir`, `--url`)
@@ -77,34 +78,34 @@ Use **exactly one** input method.
 
 - `--value`: store a literal string
   ```bash
-  ctxbin ctx save --value "summary"
-  ctxbin agent save reviewer --value "# Agent role"
-  ctxbin skill save my-skill --value "# Skill markdown"
+  npx ctxbin ctx save --value "summary"
+  npx ctxbin agent save reviewer --value "# Agent role"
+  npx ctxbin skill save my-skill --value "# Skill markdown"
   ```
 
 - `--file`: store file contents
   ```bash
-  ctxbin ctx save --file context.md
-  ctxbin agent save reviewer --file agent.md
-  ctxbin skill save my-skill --file SKILL.md
+  npx ctxbin ctx save --file context.md
+  npx ctxbin agent save reviewer --file agent.md
+  npx ctxbin skill save my-skill --file SKILL.md
   ```
 
 - `--dir`: store a directory as a skillpack (skill-only)
   ```bash
-  ctxbin skill save my-skill --dir ./skills/my-skill
-  ctxbin skill load my-skill --dir ./tmp/my-skill
+  npx ctxbin skill save my-skill --dir ./skills/my-skill
+  npx ctxbin skill load my-skill --dir ./tmp/my-skill
   ```
 
 - `--url` (+ `--path`, optional `--ref`): GitHub directory reference (skill-only)
   ```bash
   # Pin to a specific commit
-  ctxbin skill save my-skill \
+  npx ctxbin skill save my-skill \
     --url https://github.com/OWNER/REPO \
     --ref <40-hex-commit-sha> \
     --path skills/my-skill
 
   # Track default branch (omit --ref)
-  ctxbin skill save my-skill \
+  npx ctxbin skill save my-skill \
     --url https://github.com/OWNER/REPO \
     --path skills/my-skill
   ```
@@ -113,9 +114,9 @@ Use **exactly one** input method.
 `--append` works with **string inputs only**.
 
 ```bash
-ctxbin ctx save --append --value "more notes"
-ctxbin agent save reviewer --append --value "extra role details"
-ctxbin skill save my-skill --append --value "extra string"
+npx ctxbin ctx save --append --value "more notes"
+npx ctxbin agent save reviewer --append --value "extra role details"
+npx ctxbin skill save my-skill --append --value "extra string"
 ```
 
 ## What agents must include in ctx
@@ -134,4 +135,3 @@ Context is stored in Upstash Redis hash `ctx` under field `{project}/{branch}`.
 ## Do Not
 - Don’t store secrets
 - Don’t overwrite with trivial messages
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxbin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Minimal deterministic CLI to store/load context, agents, and skills via Redis hashes",
   "author": "superlucky84",
   "license": "MIT",
@@ -44,6 +44,9 @@
   },
   "scripts": {
     "build": "tsup && node scripts/copy-skills.js",
-    "test": "pnpm build && node --test \"tests/**/*.test.js\""
+    "test": "pnpm build && node --test \"tests/**/*.test.js\"",
+    "clean": "pnpm clean:dist && pnpm clean:module",
+    "clean:dist": "rm -rf dist docs/dist",
+    "clean:module": "rm -rf dist docs/dist node_modules"
   }
 }

package/skills/ctxbin/SKILL.md

@@ -5,6 +5,7 @@ Help agents preserve and restore **branch-scoped project context** so the next a
 
 ## Core Usage (ctx)
 `ctx` automatically derives a key from the current Git repo and branch when omitted.
+Prefer `npx ctxbin ...` when running commands in agent workflows.
 
 ```
 key = {project}/{branch}
@@ -14,54 +15,54 @@ branch  = git rev-parse --abbrev-ref HEAD
 
 ### Save (most common)
 ```bash
-ctxbin ctx save --value "summary / next steps / notes"
+npx ctxbin ctx save --value "summary / next steps / notes"
 ```
 Or via stdin:
 ```bash
-echo "summary" | ctxbin ctx save
+echo "summary" | npx ctxbin ctx save
 ```
 
 ### Load
 ```bash
-ctxbin ctx load
+npx ctxbin ctx load
 ```
 
 ### List
 ```bash
-ctxbin ctx list
+npx ctxbin ctx list
 ```
 
 ### Delete
 ```bash
-ctxbin ctx delete
+npx ctxbin ctx delete
 ```
 
 ## agent Save/Load
 `agent` requires a key and stores **string values only**.
 
 ```bash
-ctxbin agent save reviewer --value "# Agent role"
-ctxbin agent load reviewer
+npx ctxbin agent save reviewer --value "# Agent role"
+npx ctxbin agent load reviewer
 ```
 
 ### List/Delete
 ```bash
-ctxbin agent list
-ctxbin agent delete reviewer
+npx ctxbin agent list
+npx ctxbin agent delete reviewer
 ```
 
 ## skill Save/Load
 `skill` requires a key.
 
 ```bash
-ctxbin skill save my-skill --value "# Skill markdown"
-ctxbin skill load my-skill
+npx ctxbin skill save my-skill --value "# Skill markdown"
+npx ctxbin skill load my-skill
 ```
 
 ### List/Delete
 ```bash
-ctxbin skill list
-ctxbin skill delete my-skill
+npx ctxbin skill list
+npx ctxbin skill delete my-skill
 ```
 
 ## Input Options (`--file`, `--value`, `--dir`, `--url`)
@@ -69,34 +70,34 @@ Use **exactly one** input method.
 
 - `--value`: store a literal string
   ```bash
-  ctxbin ctx save --value "summary"
-  ctxbin agent save reviewer --value "# Agent role"
-  ctxbin skill save my-skill --value "# Skill markdown"
+  npx ctxbin ctx save --value "summary"
+  npx ctxbin agent save reviewer --value "# Agent role"
+  npx ctxbin skill save my-skill --value "# Skill markdown"
   ```
 
 - `--file`: store file contents
   ```bash
-  ctxbin ctx save --file context.md
-  ctxbin agent save reviewer --file agent.md
-  ctxbin skill save my-skill --file SKILL.md
+  npx ctxbin ctx save --file context.md
+  npx ctxbin agent save reviewer --file agent.md
+  npx ctxbin skill save my-skill --file SKILL.md
   ```
 
 - `--dir`: store a directory as a skillpack (skill-only)
   ```bash
-  ctxbin skill save my-skill --dir ./skills/my-skill
-  ctxbin skill load my-skill --dir ./tmp/my-skill
+  npx ctxbin skill save my-skill --dir ./skills/my-skill
+  npx ctxbin skill load my-skill --dir ./tmp/my-skill
   ```
 
 - `--url` (+ `--path`, optional `--ref`): GitHub directory reference (skill-only)
   ```bash
   # Pin to a specific commit
-  ctxbin skill save my-skill \
+  npx ctxbin skill save my-skill \
     --url https://github.com/OWNER/REPO \
     --ref <40-hex-commit-sha> \
     --path skills/my-skill
 
   # Track default branch (omit --ref)
-  ctxbin skill save my-skill \
+  npx ctxbin skill save my-skill \
     --url https://github.com/OWNER/REPO \
     --path skills/my-skill
   ```
@@ -105,9 +106,9 @@ Use **exactly one** input method.
 `--append` works with **string inputs only**.
 
 ```bash
-ctxbin ctx save --append --value "more notes"
-ctxbin agent save reviewer --append --value "extra role details"
-ctxbin skill save my-skill --append --value "extra string"
+npx ctxbin ctx save --append --value "more notes"
+npx ctxbin agent save reviewer --append --value "extra role details"
+npx ctxbin skill save my-skill --append --value "extra string"
 ```
 
 ## What agents must include in ctx
@@ -126,4 +127,3 @@ Context is stored in Upstash Redis hash `ctx` under field `{project}/{branch}`.
 ## Do Not
 - Don’t store secrets
 - Don’t overwrite with trivial messages
-