paqad-ai 0.0.1 → 0.0.5

package/README.md

@@ -1,27 +1,233 @@
 # 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 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.
 
-## 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
+
+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 .
 ```
 
-## Commands
+## What paqad-ai Generates
+
+Depending on the detected stack and selected options, `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/`
+- 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 .
+```
+
+Examples:
+
+```bash
+paqad-ai onboard --project-root . --domain coding --stack laravel --capability boost
+paqad-ai onboard --project-root . --domain coding --stack flutter
+```
+
+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`.
+
+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
+
+### `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 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 .
+```
+
+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).