@codesummary/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,280 +1,233 @@
 # CodeSummary CLI
 
-Dependency-free Node CLI for submitting a local workspace to CodeSummary.
-The hosted flow can log in with OAuth, create or link a private docs site,
-upload a local source snapshot, and start knowledge updates from the repo
-directory.
+Submit a local codebase to CodeSummary, generate or update hosted knowledge,
+and optionally run documentation generation locally with your own provider.
 
 ## Install
 
-Before npm publication, install from the private GitHub repo:
-
 ```bash
-npm install -g github:CodeSummaryAI/codesummary-cli
+npm install -g @codesummary/cli
 ```
 
-After npm publication:
+Verify the install:
 
 ```bash
-npm install -g @codesummary/cli
+codesummary --version
 ```
 
-Then run it from a repo:
+## Quickstart
+
+Run these commands from the repository you want CodeSummary to understand:
 
 ```bash
-codesummary login --api-url https://dashboard.codesummary.io
+codesummary login
 codesummary
 ```
 
-Bare `codesummary` is the normal workflow. It inspects the current repo and
-guides the user through creating or updating the CodeSummary knowledge source.
+The interactive `codesummary` command detects the current workspace, signs in
+with your CodeSummary account, creates or links a private docs site, uploads the
+source snapshot, and starts the right knowledge job.
 
-## Install Smoke
+After the first run, use the same command to update knowledge:
+
+```bash
+codesummary
+```
 
-From this repo, verify the packaged binary path before release:
+## Common Commands
 
 ```bash
-npm test
-npm run test:package
-npm run release:check
+codesummary                         # interactive hosted workflow
+codesummary login                   # sign in with CodeSummary OAuth
+codesummary whoami                  # show current account/workspace state
+codesummary status                  # show latest job status
+codesummary status --wait           # follow latest job until it finishes
+codesummary diff                    # compare local files to last submitted manifest
+codesummary manifest                # write .codesummary/manifest.json
+codesummary logout                  # remove local CLI auth for this workspace
 ```
 
-`test:package` runs `npm pack`, installs the tarball into a temporary project,
-and verifies that the installed `codesummary` binary starts correctly inside a
-repo workspace.
+## Initialize A Workspace
 
-## Commands
+Use `new` when you want to create or prepare a workspace before generating
+knowledge:
 
 ```bash
-codesummary
-codesummary new ./my-service --api-url https://dashboard.codesummary.io
-codesummary login --api-url https://dashboard.codesummary.io
-codesummary config set apiUrl https://dashboard.codesummary.io
-codesummary config get apiUrl
-codesummary config clear apiUrl
-codesummary link --site-token <csp_token> --api-url https://dashboard.codesummary.io --name my-repo
-codesummary manifest
-codesummary diff
-codesummary export --output ./codesummary-export
-codesummary export --output s3://my-bucket/path --include-archive
-codesummary generate --provider codex --output ./docs
-codesummary generate --provider openai --api-key-env OPENAI_API_KEY --output ./docs
-codesummary configure --provider codex --output ./docs
-codesummary generate
-codesummary submit --depth standard
-codesummary status
-codesummary submit --depth standard --wait
-codesummary version
-codesummary update
+codesummary new ./my-service
 ```
 
-Bare `codesummary` starts the interactive hosted workflow. It inspects the
-current directory, OAuth state, linked site, last submitted manifest, and local
-diff, then offers the right action:
+For an existing repo:
 
-- fresh repo: create a private docs site and generate knowledge, or check setup without generation
-- existing repo with changes: update knowledge, check setup without generation, or show the diff
-- existing repo with no changes: refresh anyway, check setup without generation, or exit
+```bash
+codesummary new --name my-service --force
+```
 
-`new` initializes a local CodeSummary workspace. It creates
-`.codesummary/config.json`, stores the source name/API URL, and never deletes
-existing files. If you point it at a non-empty directory, pass `--force` to
-confirm you want to initialize that directory in place.
+`new` creates `.codesummary/config.json` and stores local defaults. It does not
+delete source files, call CodeSummary hosted services, or start generation.
 
-`config` manages persistent workspace defaults:
+## Configuration
+
+Workspace configuration lives in `.codesummary/config.json`.
 
 ```bash
 codesummary config list
+codesummary config get apiUrl
 codesummary config set apiUrl https://dashboard.codesummary.io
 codesummary config set sourceName my-service
 codesummary config set depth standard
-codesummary config set localGeneration.provider codex
-codesummary config get sourceName
 codesummary config clear depth
 ```
 
-Supported keys are `apiUrl`, `sourceName`, `depth`, `site.id`, `site.slug`,
-`site.name`, `localGeneration.provider`, `localGeneration.output`,
-`localGeneration.model`, and `localGeneration.apiKeyEnv`.
-
-`link` verifies the token, records the existing site it belongs to, and stores
-local settings in `.codesummary/config.json`. It does not create a new hosted
-site. The token determines which existing site receives future draft knowledge
-updates.
-
-`submit` creates `.codesummary/manifest.json`, zips the current workspace, uploads it to
-`/api/cli/submit`, links the source to the token's existing site, and enqueues a knowledge job.
-The manifest is sent as separate metadata so CodeSummary can track file hashes
-without relying on the uploaded source archive.
-When the source is linked to an existing site, the backend also enqueues a site
-draft update after the repo knowledge job completes.
-`--no-generate` is a no-spend setup check: it stores manifest metadata and
-source/site linkage, but does not retain the uploaded source archive.
-The CLI stores the last submitted job id in `.codesummary/config.json`, so
-`codesummary status` can check it without passing `--job-id`. Status responses
-include both the repo job and the latest linked site job when a site update is
-running.
-
-After a successful submit, the CLI stores
-`.codesummary/last-submitted-manifest.json`. `codesummary diff` compares the
-current workspace against that baseline and reports added, changed, and removed
-files without uploading anything. Use `--against <manifest.json>` to compare
-against a specific baseline.
-
-`export` creates a local or S3 bundle without calling CodeSummary hosted
-infrastructure. By default it exports only manifest metadata and does not include
-source contents. Pass `--include-archive` only when writing to infrastructure you
-control.
-
-## Auth
-
-Use OAuth for the normal developer workflow:
+Supported keys:
+
+- `apiUrl`
+- `sourceName`
+- `depth`
+- `site.id`
+- `site.slug`
+- `site.name`
+- `localGeneration.provider`
+- `localGeneration.output`
+- `localGeneration.model`
+- `localGeneration.apiKeyEnv`
+
+## Hosted Knowledge Updates
+
+Use the hosted workflow when you want CodeSummary to generate or update the
+private draft for a docs site without committing generated files to your repo:
 
 ```bash
-codesummary login --api-url https://dashboard.codesummary.io
+codesummary login
 codesummary
 ```
 
-Product/site tokens with `write:knowledge` or `write:all` scope are still
-supported for scripted or site-bound workflows.
+The CLI uploads a filtered source snapshot and a manifest. CodeSummary uses the
+snapshot to run the knowledge job, then tracks future changes with the manifest.
 
-```bash
-export CODESUMMARY_API_KEY=csp_...
-export CODESUMMARY_API_URL=https://dashboard.codesummary.io
-codesummary link --site-token "$CODESUMMARY_API_KEY" --api-url "$CODESUMMARY_API_URL" --name my-repo
-codesummary submit --name my-repo --depth standard
-codesummary status --wait
-```
+The archive excludes common dependency, build, cache, and secret files:
+
+- `.git`
+- `node_modules`
+- `.next`
+- `dist`
+- `build`
+- `coverage`
+- `.codesummary`
+- `.env`
+- `.env.*`
+- `.npmrc`
+- `.yarnrc`
 
-## Existing Site Updates
+Publishing the docs site is a separate dashboard action.
 
-The intended hosted workflow is:
+## Non-Interactive Submit
+
+For scripts or CI-style usage:
 
 ```bash
-codesummary login --api-url https://dashboard.codesummary.io
-codesummary
+codesummary submit --depth standard
+codesummary status --wait
 ```
 
-The local directory becomes a CLI CodeSummary source linked to the selected or
-auto-created private site. Later runs update that same source and can enqueue a
-site draft update when the source knowledge job completes. Publishing the site
-is still a separate dashboard action.
+To verify setup without starting generation:
 
-Use `--depth standard` for the default update path. The CLI defaults to
-`standard`; `deep` is available for a more expensive full-context pass.
-
-## Defaults
+```bash
+codesummary submit --no-generate
+```
 
-The archive excludes common build/cache folders and secret files:
+Product or site tokens are supported for scripted workflows:
 
-- `.git`, `node_modules`, `.next`, `dist`, `build`, `coverage`
-- `.codesummary`, `.env`, `.env.*`, `.npmrc`, `.yarnrc`
+```bash
+export CODESUMMARY_API_KEY=csp_...
+export CODESUMMARY_API_URL=https://dashboard.codesummary.io
 
-The manifest stores file paths, sizes, mtimes, and SHA-256 hashes. It does not
-store file contents.
+codesummary link --site-token "$CODESUMMARY_API_KEY" --name my-repo
+codesummary submit --depth standard
+codesummary status --wait
+```
 
-## Local / BYO Output
+## Local Export
 
-For teams that do not want to upload source code to CodeSummary, export a bundle
-locally:
+Export manifest metadata without calling CodeSummary hosted infrastructure:
 
 ```bash
 codesummary export --output ./codesummary-export
 ```
 
-The bundle contains:
+The export includes:
 
 - `codesummary-manifest.json`
 - `codesummary-export.json`
 - `README.md`
 
-To include the excluded-source-filtered archive in your own storage, opt in:
+To include a filtered source archive in storage you control:
 
 ```bash
 codesummary export --output s3://my-bucket/codesummary/my-repo --include-archive
 ```
 
-S3 output uses the local `aws s3 sync` command and your existing AWS credentials.
+S3 output uses your local AWS credentials through `aws s3 sync`.
 
-## Local Inference
+## Local Generation
 
-`generate` runs documentation inference locally. It does not upload source code
-or provider credentials to CodeSummary.
+Run documentation generation locally when you do not want to upload source code
+to CodeSummary hosted infrastructure.
 
-Use the local Codex subscription/session:
+Use your local Codex CLI session:
 
 ```bash
 codesummary generate --provider codex --output ./docs
 ```
 
-Configure the workspace once, then omit flags:
+Configure defaults once:
 
 ```bash
 codesummary configure --provider codex --output ./docs
 codesummary generate
 ```
 
-Bare `codesummary` is reserved for the hosted interactive workflow. Local
-inference remains explicit with `codesummary generate` so it never spends local
-provider credits by surprise.
-
-Use a provider API key from your local environment:
+Use a local provider API key:
 
 ```bash
 export OPENAI_API_KEY=sk-...
 codesummary generate --provider openai --api-key-env OPENAI_API_KEY --output ./docs
-codesummary configure --provider openai --api-key-env OPENAI_API_KEY --output ./docs
 
 export ANTHROPIC_API_KEY=sk-ant-...
 codesummary generate --provider anthropic --api-key-env ANTHROPIC_API_KEY --output ./docs
-codesummary configure --provider anthropic --api-key-env ANTHROPIC_API_KEY --output ./docs
 ```
 
-Safe smoke test without inference:
+Dry-run local packaging without inference:
 
 ```bash
-codesummary generate --provider mock --output ./docs
 codesummary generate --provider codex --output ./docs --dry-run
 ```
 
-Local generation creates `.codesummary/manifest.json`, builds a local context
-pack from non-secret text files, asks the selected local provider to return a
-strict JSON document set, validates the result, and writes Markdown files to the
-output directory.
-
-Security model:
+Local generation does not send provider keys to CodeSummary. Provider keys stay
+in your local environment, and `.codesummary/config.json` stores only the
+provider name and environment variable name.
 
-- Provider keys stay in local environment variables.
-- `.codesummary/config.json` stores the provider choice and env var name, not the
-  provider key value.
-- Codex mode uses the local Codex CLI/session; CodeSummary never sees that
-  credential.
-- Source contents are sent only to the selected local provider.
-- CodeSummary hosted infrastructure is not called by `generate`.
-- Publishing or hosted site updates remain separate commands/flows.
+## Version And Updates
 
-## Staging E2E
+```bash
+codesummary version
+codesummary update
+```
 
-For CodeSummary maintainers, the current no-spend staging hosted-flow check is:
+`update` prints the npm command for upgrading the CLI:
 
 ```bash
-codesummary login --api-url https://dashboard-staging.codesummary.io
-codesummary whoami
-codesummary diff
-codesummary status
+npm install -g @codesummary/cli@latest
 ```
 
-For package/local CLI regressions:
+## Maintainer Checks
+
+Before releasing a new version:
 
 ```bash
 npm test
 npm run test:package
+npm run release:check
 ```
 
-Staging defaults to mock generation, so a hosted generation run should complete
-without provider spend but will only produce deterministic test docs. Do not run
-provider-backed staging generation unless the operator explicitly approves the
-credit spend.
-
-The old `scripts/staging-e2e.sh` EC2/SSM flow is retired. Staging no longer has
-that backend EC2 shape.
+`test:package` runs `npm pack`, installs the tarball into a temporary project,
+and verifies that the installed `codesummary` binary starts correctly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codesummary/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Submit local workspaces to CodeSummary knowledge and hosted docs.",
   "type": "module",
   "bin": {