paqad-ai 0.0.4 → 0.0.9

package/README.md

@@ -1,27 +1,286 @@
 # paqad-ai
 
-Documentation-first AI agency framework for Laravel, Flutter, and short-video workflows.
+`paqad-ai` is a documentation-first AI agency framework for Laravel, Flutter, React, and Vue workflows. It scaffolds project rules, documentation, registries, health checks, and agent-facing entry files so teams can run a consistent workflow across Claude Code, Codex CLI, Gemini CLI, and Junie.
 
-## Install
+## About paqad-ai
+
+Modern AI-assisted delivery breaks down when every repository invents its own prompts, rules, and folder conventions. `paqad-ai` standardizes that layer by generating framework-owned project artifacts that keep implementation, documentation, and verification aligned.
+
+The framework is designed to help teams:
+
+- onboard projects into a repeatable AI workflow
+- keep project rules and architecture guidance visible to coding agents
+- generate structured documentation scaffolds instead of ad hoc notes
+- wire in stack-aware MCP defaults for supported environments
+- run health checks and refresh framework-managed artifacts safely
+
+## Supported Adapters
+
+`paqad-ai` currently supports:
+
+- Claude Code
+- Codex CLI
+- Gemini CLI
+- Junie for JetBrains IDEs and Junie CLI
+
+Junie support is intentionally limited to the documented repo-managed surface:
+
+- `.junie/AGENTS.md`
+- `.junie/mcp/mcp.json`
+
+## Installation
+
+Prerequisites:
+
+- Node.js 25 or newer
+- pnpm 10 or newer for local development
+
+Install globally:
 
 ```bash
-npx paqad-ai install
-# or
 npm install -g paqad-ai
 ```
 
-## Quickstart
+Or run it directly with `npx`:
+
+```bash
+npx paqad-ai install
+```
+
+## Quick Start
+
+Bootstrap the framework into an existing project:
 
 ```bash
 paqad-ai onboard --project-root .
+```
+
+Run framework health checks:
+
+```bash
+paqad-ai doctor --project-root .
+```
+
+Refresh framework-managed artifacts:
+
+```bash
+paqad-ai update --project-root .
+```
+
+## Quality Gates
+
+Local and CI verification use the same `pnpm run ci` pipeline:
+
+```bash
+pnpm run ci
+```
+
+This runs typecheck, lint, formatting checks, test coverage, and build validation. Coverage thresholds are enforced at 90% for statements, branches, functions, and lines.
+
+## What paqad-ai Generates
+
+Depending on the detected stack profile and selected providers, `paqad-ai` can generate:
+
+- adapter entry files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and `.junie/AGENTS.md`
+- project profile and onboarding metadata under `.agency/`
+- project rules under `docs/rules/`
+- module scaffolds and registries under `docs/`
+- stack docs under `docs/framework/stack/`
+- design-system and architecture guidance
+- stack-aware MCP configuration for supported adapters
+- runnable project health-check scripts
+
+## Documentation Workflow
+
+`paqad-ai` no longer exposes a standalone `document` command.
+
+Documentation creation is handled through the framework workflow after onboarding. The active agent can receive a request such as "create documentation" and the workflow will:
+
+- start from the onboarded project state in `.agency/`
+- re-check the real application from `composer.json`, `package.json`, and stack manifests
+- update the effective stack context if the live application disagrees with stored onboarding metadata
+- create canonical docs step by step
+- keep `.agency/doc-progress.json` as the canonical progress ledger
+
+## Command Reference
+
+### `install`
+
+Bootstraps the framework into a project and writes framework metadata.
+
+```bash
+paqad-ai install --project-root .
+```
+
+Options:
+
+- `--project-root <path>`: target project directory. Defaults to the current working directory.
+
+Behavior:
+
+- creates the framework home directory if needed
+- writes framework version metadata for the target project
+- prints a JSON result with `framework_home`, `project_root`, and `version`
+
+### `onboard`
+
+Runs full project onboarding and generates the framework-managed scaffold.
+
+```bash
+paqad-ai onboard --project-root .
+```
+
+When run without flags in an interactive terminal, `onboard` prompts for:
+
+1. **Providers** — multi-select: Codex, Claude Code, Gemini, Junie (one or more required).
+2. **Domain** — currently `coding` is the primary shipped workflow.
+3. **Manifest-driven stack scan** — `composer.json`, `package.json`, lockfiles, and supported config files are scanned first.
+4. **Fallback stack details** — only shown when detection is missing or ambiguous. Laravel asks for Inertia, Frontend (None / React.js / Vue.js), Tailwind, Boost. React asks for app type and Tailwind. Vue asks for app type and Tailwind.
+
+Examples (non-interactive / CI):
+
+```bash
+# Laravel with React and Tailwind, Claude Code only
+paqad-ai onboard --project-root . --stack laravel --capability react tailwind --providers claude-code
+
+# Flutter with all providers
+paqad-ai onboard --project-root . --stack flutter
+
+# Next.js with Tailwind
+paqad-ai onboard --project-root . --stack react --capability next tailwind
+
+# Plain Laravel
+paqad-ai onboard --project-root . --stack laravel
+```
+
+Options:
+
+- `--project-root <path>`: target project directory. Defaults to the current working directory.
+- `--domain <domain>`: force the target domain. Current values are `coding` and `content`.
+- `--stack <stack>`: fallback/manual override for the target stack. Values: `laravel`, `flutter`, `react`, `vue`, `short-video`.
+- `--capability <capability...>`: fallback/manual trait override — `inertia`, `react`, `vue`, `tailwind`, `boost`, `next`, `remix`, `vite-spa`, `gatsby`, `nuxt`, `quasar`.
+- `--providers <provider...>`: one or more providers — `codex-cli`, `claude-code`, `gemini-cli`, `junie`.
+
+Supported capabilities per stack:
+
+| Stack   | Capabilities                                      |
+| ------- | ------------------------------------------------- |
+| Laravel | `inertia`, `react`, `vue`, `tailwind`, `boost`    |
+| Flutter | _(none)_                                          |
+| React   | `next`, `remix`, `vite-spa`, `gatsby`, `tailwind` |
+| Vue     | `nuxt`, `vite-spa`, `quasar`, `tailwind`          |
+
+Notes:
+
+- `react` and `vue` are mutually exclusive. Select only one frontend framework.
+- Standalone React and Vue projects are supported directly; Laravel continues to use `react` and `vue` as capabilities when paired with backend-driven frontend code.
+- Standalone React/Vue onboarding copies the selected sub-stack rule bundle, so `next`, `remix`, `vite-spa`, `gatsby`, `nuxt`, and `quasar` each bring their own project rules when selected.
+- Laravel testing commands now detect Pest and PHPUnit from Composer dependencies and write the matching defaults into the generated project profile.
+- Docker, Docker Compose, and Laravel Sail are detected as environment traits and mirrored into `.agency/stack-snapshot.json` and `docs/framework/stack/`.
+- Stack truth is stored canonically in `.agency/stack-snapshot.json` and mirrored for humans under `docs/framework/stack/`.
+- If no `--providers` flag is passed in a non-interactive context, files for all four providers are generated.
+- Onboarding is idempotent: running it twice with the same selections produces the same output.
+
+Behavior:
+
+- runs project detection
+- resolves rules, agents, skills, MCP configs, templates, and scripts from the detected stack profile plus any fallback/manual overrides
+- generates provider-specific entry files only for the selected providers
+- writes `.agency/project-profile.yaml`, `.agency/onboarding-manifest.json`, `.agency/stack-snapshot.json`, `.agency/stack-drift.json`, and related framework artifacts
+
+### `doctor`
+
+Runs framework health checks and prints a machine-readable report.
+
+```bash
 paqad-ai doctor --project-root .
+```
+
+Options:
+
+- `--project-root <path>`: target project directory. Defaults to the current working directory.
+
+Behavior:
+
+- validates framework artifacts, profile schema, docs scaffold, indexes, scripts, hooks, adapter config, MCP config, and other generated assets
+- prints a JSON health report
+- exits with code `1` when overall status is `fail`, otherwise `0`
+
+### `refresh`
+
+Refreshes derived framework artifacts without running full onboarding.
+
+```bash
+paqad-ai refresh --project-root .
+```
+
+Examples:
+
+```bash
+paqad-ai refresh --project-root . --design-system
+paqad-ai refresh --project-root . --stack
+```
+
+Options:
+
+- `--project-root <path>`: target project directory. Defaults to the current working directory.
+- `--design-system`: refresh design-system markdown from design tokens.
+- `--stack`: refresh the cached stack snapshot.
+
+Behavior:
+
+- refreshes design-system docs when enabled
+- refreshes stack introspection snapshots and `docs/framework/stack/**` when enabled
+- when no specific refresh flags are passed, both refresh paths run
+
+### `update`
+
+Regenerates framework-managed artifacts for an already onboarded project.
+
+```bash
 paqad-ai update --project-root .
 ```
 
-## Commands
+Options:
+
+- `--project-root <path>`: target project directory. Defaults to the current working directory.
+
+Behavior:
+
+- reads the existing project profile and onboarding manifest
+- regenerates framework-owned artifacts in a temporary workspace
+- updates auto-managed files in the target project
+- prints a JSON report with regenerated files, skipped files, and new scripts
+
+Use `update` when the package version changes or when framework-managed scaffolding needs to be refreshed without re-running project setup decisions.
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Run the full project checks:
+
+```bash
+pnpm run ci
+```
+
+Useful local commands:
+
+```bash
+pnpm run test
+pnpm run typecheck
+pnpm run lint
+pnpm run build
+```
+
+## Contributing
+
+Contributions that improve framework reliability, adapter support, documentation quality, or stack coverage are welcome. Keep changes aligned with the framework’s documentation-first approach and ensure generated artifacts, validation logic, and tests remain consistent.
+
+## License
 
-- `install`: bootstrap stable framework metadata into a project
-- `onboard`: generate framework-owned project scaffolding
-- `doctor`: run health checks
-- `refresh`: refresh framework indexes and registries
-- `update`: regenerate framework-managed artifacts
+`paqad-ai` is open-sourced software licensed under the [MIT license](LICENSE).