codiedev 0.3.3 → 0.3.4

package/dist/cli.js

@@ -25,6 +25,10 @@ const promote_1 = require("./commands/promote");
 const HELP = `
 CodieDev CLI
 
+  The team artifact layer for agent-coded work. Share specs and reviews
+  with teammates, get pinged when they need your input, pick up where
+  someone left off across sessions and providers.
+
 Connect:
   codiedev connect                       Link Claude Code / Codex to your org
 
@@ -45,19 +49,260 @@ Capture:
   codiedev note "<text>"                 Capture a passing thought
 
 Other:
-  codiedev help                          Show this help
+  codiedev help [command]                Show this help, or details for one command
+  codiedev docs                          Print the full usage guide
   codiedev version                       Show version
 
+Filename conventions:
+  spec-*.md      → spec          review-*.md    → review
+  decision-*.md  → decision      proposal-*.md  → proposal
+  bugfix-*.md    → bugfix        anything else  → note
+
+Examples:
+  codiedev push docs/specs/spec-cart-clear.md
+  codiedev pull spec-cart-clear.md
+  codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+  codiedev inbox --unread
+  codiedev note "idempotency key is worth a follow-up"
+
 Backend: ${process.env.CODIEDEV_URL ?? "https://codiedev.com"}
+Token:   https://codiedev.com/portal/integrations/claude-code
+Docs:    codiedev docs
+`.trim();
+const COMMAND_HELP = {
+    connect: `
+codiedev connect — link your agent CLI to CodieDev
+
+  Interactive setup. Prompts for an API token, then installs:
+    - ~/.codiedev/config.json            (token + org + tracked repos)
+    - ~/.claude/settings.json hook       (captures session transcripts)
+    - ~/.claude/CLAUDE.md instructions   (teaches Claude the commands)
+    - ~/.codex/hooks.json hook           (same, for Codex)
+    - ~/.codex/AGENTS.md instructions    (same, for Codex)
+
+  Re-run anytime to swap accounts or refresh the instruction block.
+
+  Get your token: https://codiedev.com/portal/integrations/claude-code
+`.trim(),
+    push: `
+codiedev push — author or update an artifact
+
+  Usage:
+    codiedev push <file.md> [--type spec|review|decision|proposal|bugfix|note]
+
+  The file's basename becomes its key (unique per company). Pushing the
+  same key again creates a new version — full history is preserved.
+
+  Type is inferred from the filename prefix unless you override with --type.
+
+  Examples:
+    codiedev push spec-cart-clear.md
+    codiedev push docs/review-auth.md --type review
+    codiedev push notes/random.md --type note
+`.trim(),
+    pull: `
+codiedev pull — fetch an artifact
+
+  Usage:
+    codiedev pull <key> [--version N] [--out path.md]
+
+  By default prints to stdout (pipe-friendly). --out writes to a file.
+  --version gets a specific historical version; omit for the latest.
+
+  Examples:
+    codiedev pull spec-cart-clear.md
+    codiedev pull spec-cart-clear.md --version 2
+    codiedev pull spec-cart-clear.md --out ./local-copy.md
+    codiedev pull spec-cart-clear.md | less
+`.trim(),
+    ping: `
+codiedev ping — send a teammate a message, optionally attached to an artifact
+
+  Usage:
+    codiedev ping <user> "<message>" [--with <artifact-key>]
+
+  <user> resolves to a teammate in your org by first name, full name,
+  or email. Ambiguous matches return a list — retry with the full email.
+
+  Teammates are notified by email and can reply from their own agent.
+
+  Examples:
+    codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+    codiedev ping nic@signalandcode.co "can you take this one?"
+`.trim(),
+    inbox: `
+codiedev inbox — show messages from teammates
+
+  Usage:
+    codiedev inbox [--unread] [--limit N]
+
+  Lists pings with sender, subject artifact, and preview. Each row
+  shows a ping-id you can pass to 'codiedev read'.
+
+  Unread rows show as ● ; read rows as · .
+
+  Examples:
+    codiedev inbox
+    codiedev inbox --unread
+    codiedev inbox --limit 10
+`.trim(),
+    read: `
+codiedev read — mark a ping as read and show its full content
+
+  Usage:
+    codiedev read <ping-id>
+
+  Grab the ping-id from 'codiedev inbox'. After reading, the ping will
+  drop out of 'codiedev inbox --unread' and the portal inbox badge
+  decrements for you.
+`.trim(),
+    note: `
+codiedev note — capture a passing thought, linked to your session
+
+  Usage:
+    codiedev note "<text>"
+
+  Stores the note in your org memory so you can search it later or
+  reference it in a ticket. Notes appear in the portal under the
+  Agent Inbox → My authored artifacts.
+
+  Examples:
+    codiedev note "idempotency key is worth a follow-up"
+    codiedev note "timeout threshold feels arbitrary — validate on slow networks"
+`.trim(),
+    promote: `
+codiedev promote — promote an auto-extracted artifact to authored
+
+  Usage:
+    codiedev promote <artifact-id> [--key filename.md]
+
+  The session-capture pipeline auto-extracts spec/bugfix/decision
+  artifacts from each agent session. Promote turns one of those into
+  a first-class authored artifact your team can ping, pull, and
+  update versions of.
+
+  Find artifact-ids in the portal under Knowledge → Memory, or via
+  the portal search.
+`.trim(),
+};
+const DOCS = `
+CodieDev — usage guide
+
+## What this is
+
+CodieDev is a team artifact layer on top of your coding agent (Claude
+Code, Codex, etc.). It persists the *durable* outputs of agent work —
+specs, reviews, decisions, proposals, and captured thoughts — so:
+
+  - Your teammates can pick up where you left off without a handoff call.
+  - Your manager can see what's shipping and why, grounded in real
+    session evidence.
+  - Your future self can search "what did we decide about X?" and get
+    a real answer with citations.
+
+## Core loop
+
+  1. You push an artifact:
+       codiedev push spec-cart-clear.md
+
+  2. Your teammate gets pinged (either directly by you, or because
+     they asked to be kept in the loop on that key):
+       codiedev ping maya "thoughts?" --with spec-cart-clear.md
+
+  3. They check their inbox:
+       codiedev inbox
+
+  4. They pull your artifact, edit it, and push back:
+       codiedev pull spec-cart-clear.md > my-copy.md
+       # ...edit...
+       codiedev push my-copy.md   (saves as v2 of the same key)
+
+  5. You pull the updated version and keep building.
+
+## Versions
+
+Every push of the same filename creates a new version. Latest is the
+default on pull; use --version N to get a historical one. All versions
+are preserved — you can always roll back.
+
+## Lifecycle
+
+Artifacts have a status that auto-advances as PRs reference them:
+
+  draft  →  accepted  →  implementing  →  shipped
+                                       →  archived
+
+Artifacts stay editable at every stage, including after merge —
+lessons-learned and follow-up notes append as new versions.
+
+## Portal
+
+Everything you do in the CLI is visible at:
+
+    https://codiedev.com/portal/inbox
+
+Your CTO (or any non-technical teammate) can follow along without ever
+touching a terminal — they read the artifacts in the portal and get
+email notifications when pinged.
+
+## Agent-native
+
+If you use Claude Code or Codex, the agent already knows the commands —
+'codiedev connect' installs instructions into your user-level config.
+Just say things like:
+
+    "push this spec and ping Nic"
+    "any messages?"
+    "pull Maya's latest spec"
+
+The agent will run the right command via Bash.
+
+## Command reference
+
+Run 'codiedev help <command>' for each, or see the quick list:
+
+    codiedev help
+
+## Getting a token
+
+  1. Log in to https://codiedev.com/portal/integrations/claude-code
+  2. Click "Create token"
+  3. Copy the cdv_... string and paste it into 'codiedev connect'
+
+Tokens are per-user. Rotate any time by revoking + creating a new one.
 `.trim();
 async function main() {
     const [, , command, ...rest] = process.argv;
-    if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (!command || command === "--help" || command === "-h") {
         console.log(HELP);
         return;
     }
+    if (command === "help") {
+        const sub = rest[0];
+        if (sub && COMMAND_HELP[sub]) {
+            console.log(COMMAND_HELP[sub]);
+            return;
+        }
+        if (sub) {
+            console.log(`No help for "${sub}". Valid commands:`);
+            console.log(Object.keys(COMMAND_HELP).join(", "));
+            return;
+        }
+        console.log(HELP);
+        return;
+    }
+    if (command === "docs") {
+        console.log(DOCS);
+        return;
+    }
+    // Support `codiedev <command> --help` too.
+    if (rest.includes("--help") || rest.includes("-h")) {
+        if (COMMAND_HELP[command]) {
+            console.log(COMMAND_HELP[command]);
+            return;
+        }
+    }
     if (command === "version" || command === "--version" || command === "-v") {
-        // Package version is replaced at publish via tsc — for now, print the source-of-truth.
         console.log("codiedev cli");
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codiedev",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Connect Claude Code or Codex to CodieDev for org-wide session capture and artifact collaboration",
   "bin": {
     "codiedev": "./dist/cli.js",