paqad-ai 0.0.5 → 0.0.9

package/README.md

@@ -1,6 +1,6 @@
 # paqad-ai
 
-`paqad-ai` is a documentation-first AI agency framework for Laravel and Flutter 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.
+`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.
 
 ## About paqad-ai
 
@@ -30,6 +30,11 @@ Junie support is intentionally limited to the documented repo-managed surface:
 
 ## Installation
 
+Prerequisites:
+
+- Node.js 25 or newer
+- pnpm 10 or newer for local development
+
 Install globally:
 
 ```bash
@@ -62,14 +67,25 @@ Refresh framework-managed artifacts:
 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 and selected options, `paqad-ai` can generate:
+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
@@ -114,26 +130,63 @@ Runs full project onboarding and generates the framework-managed scaffold.
 paqad-ai onboard --project-root .
 ```
 
-Examples:
+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
-paqad-ai onboard --project-root . --domain coding --stack laravel --capability boost
-paqad-ai onboard --project-root . --domain coding --stack flutter
+# 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>`: force the target stack. Current values are `laravel`, `flutter`, and `short-video`.
-- `--capability <capability...>`: add one or more capabilities such as `boost`.
+- `--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
-- generates adapter entry files including Junie support
-- writes `.agency/project-profile.yaml`, `.agency/onboarding-manifest.json`, and related framework artifacts
+- 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`
 
@@ -177,7 +230,7 @@ Options:
 Behavior:
 
 - refreshes design-system docs when enabled
-- refreshes stack introspection snapshots when enabled
+- refreshes stack introspection snapshots and `docs/framework/stack/**` when enabled
 - when no specific refresh flags are passed, both refresh paths run
 
 ### `update`