benjamin-docs 0.1.1 → 0.1.2

package/README.md

@@ -1,269 +1,99 @@
 # benjamin-docs
 
-Repo-local project memory for humans and AI agents.
+Local project memory for humans and AI agents.
 
-`benjamin-docs` turns planning and build conversations into structured Markdown docs that live inside your project. It works before code exists, inside existing codebases, and for individual feature scopes.
+`benjamin-docs` turns useful chats into project docs.
 
-## Status
+It keeps decisions, plans, open questions, and handoff notes in Markdown files inside your project.
 
-Early MVP. The CLI is prepared for its first public `0.1.0` package release as `benjamin-docs`.
+No cloud. No dashboard. No transcript dump.
 
-The current goal is to make the open-source repo useful, understandable, and safe to try before adding hosted publishing or SaaS features.
+## What It Solves
 
-## Why It Exists
+AI work gets lost in chat history.
 
-Long agent sessions create valuable project context: product decisions, rejected options, feature plans, user-facing notes, handoff context, and code references. That context is easy to lose.
+You explain the same context again.
 
-`benjamin-docs` keeps that memory close to the work:
+Future agents miss decisions.
 
-- human-readable Markdown in `benjamin-docs/`
-- machine-readable metadata in `.benjamin-docs/`
-- local validation before docs are shared or exported
-- agent skill guidance so future sessions can update docs without drifting
+Projects drift.
 
-## Try It From Any Chat
+`benjamin-docs` gives the project a small local notebook that agents can keep up to date.
 
-If a conversation already contains a useful project idea, ask your agent:
+## Install
 
-```text
-Use the benjamin-docs skill to create a project from this chat.
+```bash
+pnpm add -g benjamin-docs
+benjamin-docs install-skill
+benjamin-docs introduce
 ```
 
-The agent should suggest a local folder like:
+`install-skill` installs the bundled agent skill for common local tools:
 
 ```text
-~/Documents/Benjamin Docs/Atelier Edits
+~/.agents/skills/benjamin-docs/
+~/.codex/skills/benjamin-docs/
+~/.claude/skills/benjamin-docs/
+~/.cursor/skills/benjamin-docs/
 ```
 
-After you confirm, it creates:
+Claude Desktop / Claude.ai uses uploaded skills. After install, upload:
 
 ```text
-README.md
-benjamin-docs/
-.benjamin-docs/
+~/.claude/skills/benjamin-docs/
 ```
 
-The top-level `README.md` explains the project in plain language. The `benjamin-docs/` folder captures the project brief, roadmap, open questions, and handoff notes. Nothing is uploaded by the CLI.
-
-## For Non-Programmers
-
-You can use `benjamin-docs` even if you are planning an app, product, service, or creative project before any code exists.
-
-Think of it as a project notebook that your AI agent keeps inside your project folder. The agent does the writing; the CLI creates the folders, checks that the notes are valid, and gives the next prompt to use.
+## Use It From Any Chat
 
-You need:
-
-- a place on your computer where the agent can create a project folder, such as `~/Documents/Benjamin Docs/Project Name`
-- an AI coding agent that can run terminal commands and edit files
-- the `benjamin-docs` CLI installed with pnpm, or a local source checkout while developing
-- the `benjamin-docs` skill installed for your agent
-
-If all you have is the current chat, start by asking your agent:
+If you only have a chat and no project folder yet, ask your agent:
 
 ```text
 Use the benjamin-docs skill to create a project from this chat.
-Suggest ~/Documents/Benjamin Docs/<Project Name> as the folder,
-initialize it as a planning-only project, write a simple top-level README.md,
-then capture the current context in plain language.
 ```
 
-After that, ask:
+The agent should suggest:
 
 ```text
-Show me the benjamin-docs project brief, roadmap, open questions,
-and handoff. Explain what each file is for.
+~/Documents/Benjamin Docs/<Project Name>
 ```
 
-Nothing is uploaded or published by the CLI. The docs stay in your project folder unless you choose to share them.
-
-## Create A Project From A Chat
-
-This is the simplest first use case: you do not have a repo, codebase, or project folder yet. You only have a useful conversation.
-
-Ask your agent:
+After you confirm, it creates a local project with:
 
 ```text
-Use the benjamin-docs skill to create a project from this chat.
-Suggest ~/Documents/Benjamin Docs/<Project Name> unless I choose a different place.
-Create the folder, initialize benjamin-docs there, add a simple README.md,
-and turn this conversation into a project brief, roadmap, open questions,
-and handoff.
-```
-
-The agent should:
-
-- infer a human-readable project name when the chat makes one obvious
-- suggest `~/Documents/Benjamin Docs/<Project Name>` as the default location
-- ask for confirmation before creating files
-- summarize what it will capture in short bullets
-- create the project folder
-- run `benjamin-docs init --mode planning` inside that folder
-- write a top-level `README.md` that explains what the project is and where to start
-- update the Benjamin docs under `benjamin-docs/` from the chat context
-- run `benjamin-docs validate`
-- show you what was created and what is still uncertain
-
-The CLI creates and validates the docs workspace. The agent turns the chat into useful project memory.
-
-## Install The CLI
-
-Install globally with pnpm:
-
-```bash
-pnpm add -g benjamin-docs
-benjamin-docs install-skill
-benjamin-docs introduce
-```
-
-`install-skill` installs or updates the bundled skill in common local agent locations:
-
-```text
-~/.agents/skills/benjamin-docs/SKILL.md
-~/.codex/skills/benjamin-docs/SKILL.md
-~/.claude/skills/benjamin-docs/SKILL.md
-~/.cursor/skills/benjamin-docs/SKILL.md
+README.md
+benjamin-docs/
+.benjamin-docs/
 ```
 
-Claude Desktop / Claude.ai custom skills are uploaded through Claude's Skills UI. After running `install-skill`, use the generated `~/.claude/skills/benjamin-docs/` folder as the upload source.
+## Use It In An Existing Project
 
-Initialize docs in the current project folder:
+From the project folder:
 
 ```bash
 benjamin-docs init
-benjamin-docs status
 benjamin-docs validate
 ```
 
-`init` prints the recommended agent prompt. Run `next` later if you want to see that prompt again.
+Then ask your agent:
 
-```bash
-benjamin-docs next
+```text
+Capture the current project baseline with benjamin-docs.
 ```
 
-In an interactive terminal, `init` asks what you are setting up. In scripts or agent workflows, pass a mode explicitly.
-
 For an existing codebase:
 
 ```bash
 benjamin-docs init --mode codebase
-benjamin-docs validate
 ```
 
-For a single feature:
+For one feature:
 
 ```bash
 benjamin-docs init --mode feature --feature billing-reminders
-benjamin-docs validate
-```
-
-If you prefer a project-local dev dependency:
-
-```bash
-cd /path/to/your-project
-pnpm add -D benjamin-docs
-pnpm exec benjamin-docs init
-pnpm exec benjamin-docs validate
-```
-
-## Install The Agent Skill Locally
-
-The skill teaches an agent how to capture planning/build conversations into the docs created by the CLI.
-
-Install or update it from the published package:
-
-```bash
-benjamin-docs install-skill
-```
-
-Install one target only:
-
-```bash
-benjamin-docs install-skill --target codex
-benjamin-docs install-skill --target cursor
-benjamin-docs install-skill --target claude-code
-```
-
-Then ask your agent:
-
-```text
-Capture this conversation with benjamin-docs.
-```
-
-For a first planning session, a clearer prompt is:
-
-```text
-Use the benjamin-docs skill.
-If there is no project folder yet, ask me where to create one.
-Suggest ~/Documents/Benjamin Docs/<Project Name> by default.
-Initialize it as a planning-only project, add a simple README.md,
-and capture what we know, what we decided, what is still unclear,
-and what I should do next. Keep it understandable for a non-technical reader.
-```
-
-## Local Development
-
-```bash
-git clone https://github.com/msiksnis/benjamin-docs.git
-cd benjamin-docs
-pnpm install
-pnpm build
-node dist/src/cli.js introduce
 ```
 
-To test the source CLI inside another local project without installing the package:
-
-```bash
-cd /path/to/your-project
-node /path/to/benjamin-docs/dist/src/cli.js init
-```
-
-## Checks
-
-```bash
-pnpm check
-node dist/src/cli.js validate
-npm pack --dry-run
-```
-
-Before publishing:
-
-```bash
-pnpm run release:check
-pnpm publish
-```
-
-## Common Commands
-
-```bash
-benjamin-docs introduce
-benjamin-docs install-skill
-benjamin-docs help
-benjamin-docs --version
-benjamin-docs init
-benjamin-docs init --mode codebase
-benjamin-docs init --mode feature --feature booking-capacity
-benjamin-docs next
-benjamin-docs status
-benjamin-docs validate
-benjamin-docs scope create feature booking-capacity
-benjamin-docs anchor add booking-capacity-rules src/features/booking/capacity.ts
-benjamin-docs export --audience developer
-benjamin-docs promote --to codebase
-```
-
-In a source checkout, use `node dist/src/cli.js ...` after `pnpm build`.
-
 ## What It Creates
 
-```text
-benjamin-docs/
-.benjamin-docs/
-```
-
-`benjamin-docs/` contains human-readable Markdown. `.benjamin-docs/` contains machine metadata for validation, exports, anchors, and future publishing.
-
-The default workspace is:
-
 ```text
 benjamin-docs/
   project/
@@ -271,109 +101,51 @@ benjamin-docs/
   engineering/
   features/
   releases/
-```
-
-Existing project docs in `docs/` are left alone. They may be useful context, but they are not the Benjamin-managed workspace unless `.benjamin-docs/config.json` explicitly says so.
-
-## Agent Workflow
-
-The CLI owns structure and validation. Codex or Claude skills own synthesis from the current conversation.
-
-If the agent does not recognize `benjamin-docs`, run:
-
-```bash
-benjamin-docs install-skill
-```
-
-Ask your agent:
-
-```text
-Capture this conversation with benjamin-docs.
-```
-
-The agent should update the relevant docs, run validation, and report what changed.
-
-Good capture prompts:
-
-```text
-Use the benjamin-docs skill to create a project from this chat.
-Suggest ~/Documents/Benjamin Docs/<Project Name>, then initialize it and capture the project.
-```
 
-```text
-Capture this planning conversation with benjamin-docs.
-```
-
-```text
-Capture the current project baseline with benjamin-docs.
-Read the existing docs and codebase, then update the Benjamin docs
-under benjamin-docs/. Mark uncertain items.
-```
-
-```text
-Create a benjamin-docs feature scope for billing-reminders
-and capture the plan, decisions, risks, and handoff.
+.benjamin-docs/
 ```
 
-## Capture A Baseline
-
-A baseline capture turns the current state of a project into durable docs. It is the first useful pass after `init`, and it should capture decisions, rejected options, risks, open questions, and next actions instead of saving a raw transcript.
-
-For a new idea or planning-only project:
+`benjamin-docs/` is for people and agents.
 
-```bash
-benjamin-docs init --mode planning
-```
+`.benjamin-docs/` is metadata for validation, scopes, anchors, and exports.
 
-```text
-Capture the baseline for this new idea with benjamin-docs.
-Update the project brief, roadmap, open questions, and handoff docs.
-Mark assumptions clearly and challenge any overbuilt V1 scope.
-```
+Existing `docs/` folders are left alone unless you explicitly configure otherwise.
 
-For an existing codebase:
+## Useful Commands
 
 ```bash
-benjamin-docs init --mode codebase
-```
-
-```text
-Capture the current codebase baseline with benjamin-docs.
-Read the README, package/config files, existing docs, and major source areas.
-Update the project, engineering, and handoff docs under benjamin-docs/.
-Include important code references, risks, and uncertain findings.
+benjamin-docs introduce
+benjamin-docs install-skill
+benjamin-docs init
+benjamin-docs next
+benjamin-docs status
+benjamin-docs validate
+benjamin-docs scope create feature <slug>
+benjamin-docs export --audience developer
 ```
 
-For one feature:
+## Local Development
 
 ```bash
-benjamin-docs init --mode feature --feature billing-reminders
-```
-
-```text
-Capture the billing-reminders feature with benjamin-docs.
-Update the feature brief, plan, decisions, and handoff.
-Include user goals, constraints, rejected options, test ideas, and next actions.
+git clone https://github.com/msiksnis/benjamin-docs.git
+cd benjamin-docs
+pnpm install
+pnpm check
 ```
 
-After any baseline capture:
+Before publishing:
 
 ```bash
-benjamin-docs validate
+pnpm run release:check
+pnpm publish
 ```
 
-## Design Boundaries
-
-- The repo-local docs are the source of truth.
-- The CLI should stay deterministic and dependency-light.
-- Ordinary local commands should not make network calls.
-- Existing docs in a repo should not be overwritten.
-- Hosted publishing, auth, comments, and web editing are future layers.
-
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+Keep it local-first.
+
+Keep docs readable by non-programmers.
 
-## Security
+Keep agent workflows explicit.
 
-See [SECURITY.md](SECURITY.md).
+Avoid magic that writes outside the project unless the user runs a clear command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "benjamin-docs",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Repo-local project memory for humans and AI agents.",
   "keywords": [
     "ai",