businesslens 0.2.3 → 0.5.0

package/{THIRD_PARTY_NOTICES.md → LICENSE}

@@ -1,13 +1,6 @@
-# Third-party notices
-
-## Nuxt UI Landing Template
-
-Portions of the BusinessLens landing-page structure and visual components are
-adapted from the [Nuxt UI Landing Template](https://github.com/nuxt-ui-templates/landing).
-
 MIT License
 
-Copyright (c) 2025 Nuxt UI Templates
+Copyright (c) 2026 BusinessLens
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,138 +1,149 @@
 # BusinessLens
 
-BusinessLens turns source-backed software analysis into a local, navigable
-product report. Point the CLI at one validated JSON file and explore its
-actors, domains, journeys, scenarios, repository evidence, topology, coverage,
-and limitations in the browser.
-
-## Run a report
+**Product-Driven Design for coding agents.** BusinessLens builds a
+Git-tracked product map in `.businesslens/`: who the product serves, what they
+accomplish, and where the code proves it.
+
+The map is Markdown, reviewable in pull requests, and useful without a hosted
+service.
+
+```text
+.businesslens/
+├── product.md
+├── actors/
+├── experiences/
+├── domains/
+├── journeys/<id>/journey.md
+│   └── scenarios/<id>.md
+└── coverage.md
+```
 
-Requires Node.js 22.13 or newer.
+## Getting started
 
-```sh
-npx businesslens --report ./report.json
-```
+### 1. Install the skills
 
-BusinessLens validates the report before starting, binds to `127.0.0.1`, uses
-port 3000 or the next available port, and opens the browser. Useful options:
+Run this in the repository you want to map:
 
-```sh
-npx businesslens --report ./report.json --port 4173 --no-open
-npx businesslens --help
+```bash
+npx businesslens@latest install
 ```
 
-## Included reports
+The installer detects supported AI harnesses, lets you customize the
+selection, asks for project or global scope, and installs only the
+BusinessLens skills.
 
-This repository preserves four source-backed reports in the v2 single-file
-format:
+For automated setup:
 
-- `reports/argo-cd/report.json`
-- `reports/argo-workflows/report.json`
-- `reports/gitea/report.json`
-- `reports/vibe-trading/report.json`
+```bash
+npx businesslens@latest install \
+  --providers claude,codex,cursor \
+  --scope project \
+  --yes
+```
 
-Run one from a source checkout:
+### 2. Build the map in your AI harness
 
-```sh
-pnpm install
-pnpm build
-node bin/businesslens.mjs --report ./reports/gitea/report.json
+Invoke the initialization skill:
+
+```text
+/businesslens-init
 ```
 
-For Nuxt development, pass the absolute report path through runtime config:
+Codex users can invoke the same skill as `$businesslens-init`. The skill
+inspects the repository without executing its application, authors the full
+map, installs the managed `AGENTS.md` guidance, and validates the result.
 
-```sh
-NUXT_REPORT_PATH="$PWD/reports/gitea/report.json" pnpm dev
-```
+### 3. Review and commit
 
-## Report contract
+Review `.businesslens/`, then commit its authored files. Generated cache files
+stay ignored.
 
-Each `reports/<report-id>/` directory contains exactly one `report.json` using
-schema version `2.0.0`. It includes:
+## Terminal or agent?
 
-- report identity and generation metadata;
-- source repository, optional logo, branch or tag, and pinned commit;
-- actors and product domains;
-- user journeys with entry points and repository evidence;
-- source-backed scenarios with triggers, ordered observable steps, outcomes,
-  and edge cases;
-- analysis coverage, unmapped areas, and limitations.
+BusinessLens has two deliberate surfaces:
 
-Validate every tracked report:
+| Where | Command | Purpose |
+| --- | --- | --- |
+| Terminal | `npx businesslens install` | Install the agent skills |
+| Terminal | `npx businesslens update` | Refresh managed skill installations |
+| Terminal | `npx businesslens validate` | Deterministically validate the map |
+| Terminal | `npx businesslens build` | Compile the map into the portable project document |
+| Terminal | `npx businesslens publish` | Submit the map to the platform as a commit-pinned snapshot |
+| AI harness | `businesslens-init` | Build the initial map |
+| AI harness | `businesslens-sync` | Update the map after behavior changes |
+| AI harness | `businesslens-deep-dive` | Expand one journey or experience |
+| AI harness | `businesslens-validate` | Validate the map and explain every result |
+| AI harness | `businesslens-doctor` | Diagnose validation, drift, and coverage |
+| AI harness | `businesslens-publish` | Publish the map to the platform on explicit request |
 
-```sh
-pnpm validate
-```
+The installer never creates `.businesslens/` or modifies `AGENTS.md`. Those
+require repository analysis and belong to the initialization skill.
 
-Validate one file:
+## Skills
 
-```sh
-node .agents/skills/businesslens-validate-report/scripts/validate-report.mjs \
-  ./reports/gitea/report.json
-```
+| Skill | Use it when |
+| --- | --- |
+| `businesslens-init` | Adopting BusinessLens or rebuilding an incomplete map |
+| `businesslens-sync` | Code changes affected product behavior |
+| `businesslens-deep-dive` | One journey or experience needs exhaustive coverage |
+| `businesslens-validate` | The map needs a read-only deterministic check |
+| `businesslens-doctor` | The map fails validation, looks stale, or needs a health report |
+| `businesslens-publish` | The user explicitly wants the map on the platform |
 
-## Repository-analysis skills
+Every skill is self-contained and follows the open Agent Skills folder format.
+The CLI currently supports Claude Code, Codex, Cursor, Gemini CLI, and GitHub
+Copilot installation paths.
 
-Agents that support `AGENTS.md` and the Agent Skills convention can use the
-workflows under `.agents/skills/`:
+`businesslens-validate` is the read-only agent interface to the deterministic
+CLI validator. `businesslens-doctor` goes further: it investigates drift,
+coverage, and hygiene, and can repair problems when explicitly requested.
 
-- `$businesslens-analyze-repository` safely inventories a public HTTPS Git
-  checkout and creates a v2 `report.json` without executing target code.
-- `$businesslens-validate-report` checks schema and semantic integrity.
-- `$businesslens-add-report` imports a validated file without replacing an
-  existing report.
+Claude Code plugin users may alternatively install from this repository's
+marketplace manifest. The standalone CLI remains the primary installation
+experience.
 
-## Development tooling
+## Keep the map current
 
-The repository keeps shared MCP configuration for Codex, Claude, and other
-MCP-compatible development clients. It provides Nuxt UI documentation tools
-and a pinned Chrome DevTools integration without changing a contributor's
-sandbox or approval policy.
+1. Before changing behavior, read the relevant experiences, journeys, and
+   scenarios.
+2. Build against the repository's SDD change when one exists.
+3. Invoke `businesslens-sync` after behavior changes.
+4. Run `npx businesslens validate`.
 
-The Chrome integration expects a browser debugging endpoint on port `9222`.
-For example, on macOS:
+PDD records what **is**. OpenSpec, spec-kit, and other SDD systems prescribe
+what **will change**. BusinessLens links that intent without copying it. See
+[PDD and SDD](./docs/pdd-and-sdd.md).
 
-```sh
-open -na "Google Chrome" --args \
-  --remote-debugging-port=9222 \
-  --user-data-dir=/tmp/businesslens-chrome
+## Updating the skills
+
+```bash
+npx businesslens@latest update
 ```
 
-## Development and verification
+Update discovers BusinessLens-managed installations through ownership markers
+and refreshes only those skill directories. It does not touch `.businesslens/`
+or `AGENTS.md`.
 
-```sh
-pnpm install
-pnpm check
-```
+## Documentation
 
-Before publishing, create and smoke-test both npm artifacts from the same
-canonical package:
-
-```sh
-release_dir="$(mktemp -d)"
-version="$(node --print "require('./package.json').version")"
-pnpm pack:release "$release_dir"
-npx --package "$release_dir/businesslens-${version}.tgz" businesslens \
-  --report ./reports/gitea/report.json --no-open
-npx --package "$release_dir/businesslens-cli-${version}.tgz" cli \
-  --report ./reports/gitea/report.json --no-open
-```
+- [Introduction](./docs/index.md)
+- [Quickstart](./docs/quickstart.md)
+- [`.businesslens/` format](./docs/format.md)
+- [CLI reference](./docs/cli.md)
+- [Skills reference](./docs/skills.md)
+- [CI validation and publishing](./docs/ci.md)
+- [PDD and SDD](./docs/pdd-and-sdd.md)
 
-The canonical `businesslens` artifact exposes the `businesslens` executable.
-The compatibility `@businesslens/cli` artifact exposes both `cli` and
-`businesslens`, preserving the original command while supporting the canonical
-name. The publish workflow tests both tarballs and publishes any missing version
-to both npm package names.
-
-Trusted publishing is configured separately for each npm package. Both package
-settings must trust the GitHub Actions publisher for organization
-`businesslens`, repository `cli`, and workflow `publish.yml` with `npm publish`
-allowed. npm 11.17 or newer is required to send the allowed-action permission:
-
-```sh
-npx --yes npm@11.17.0 trust github businesslens \
-  --file publish.yml \
-  --repo businesslens/cli \
-  --allow-publish \
-  --yes
-```
+## Safety
+
+- Skills inspect target repositories statically; they do not run target code.
+- Installation refuses to overwrite unowned `businesslens-*` directories
+  unless `--force` is explicit.
+- Updates replace only artifacts marked as BusinessLens-managed.
+- No platform connection or publishing occurs during installation or mapping;
+  publishing happens only through the explicit `publish` command or the
+  `businesslens-publish` skill.
+
+## License
+
+MIT.