# Getting Started

## Install

Requires [Node.js](https://nodejs.org/) 18+.

```bash
npm install -g weyaw
```

The correct pre-built binary for your platform (Linux x64, macOS ARM64, or
Windows x64) is installed automatically via an optional dependency. No Rust
toolchain needed.

Verify:

```bash
aw --help
```

If the `pi` command is available, successful interactive runs of bare `aw` and
`aw install` also check whether Weyaw is configured as a Pi package. When it is
missing, AW prints the manual installation command:

```bash
pi install npm:weyaw
```

AW does not execute that command or write Pi settings. JSON, redirected, and
other non-interactive invocations do not probe Pi or add guidance output.

The root package also installs the documentation in its `docs/` directory. To
locate a global npm installation, run `npm root -g` and open
`weyaw/docs/getting-started.md` beneath the reported directory.

### From source

Requires Rust 1.96+ ([rustup](https://rustup.rs)):

```bash
git clone https://github.com/jsnzwu/weyaw.git
cd weyaw
cargo build --release
# Binary at target/release/aw
```

Inside a Weyaw source checkout, use the checkout-local wrapper for current
source behavior:

```bash
node bin/aw-debug.js --help
```

This prefers `WEYAW_RS_BIN` when set and otherwise uses `target/debug/aw`.
For interactive source-checkout testing, bare `node bin/aw-debug.js` and its
`install` command suggest installing the resolved checkout as a local-path Pi
package when Pi is available and Weyaw is absent. Use the packaged `aw` command
in normal installed projects; do not use a possibly older global command as
evidence for uncommitted checkout behavior.

## Quick start

### 1. Set up a project

```bash
cd your-project
aw init "This project does X, using Y stack"
aw install --target agents
```

`aw init` creates a `.aw/` workspace with a project profile, blueprint, and
roadmap seed. The description you provide helps agents understand the project
scope. `aw install --target agents` installs generated skills under
`.agents/skills/`; use `--target claude-code` for Claude Code or
`--target codex` for the legacy Codex compatibility directory.

### 2. Start a task

In an agent session, use the workflow skill:

```text
$aw-task Add rate limiting to the API
```

Weyaw creates a task with a unique ID and a full artifact workspace under
`.aw/tasks/<task-id>/`. The agent skill `$aw-task` walks through the
lifecycle: analyze → plan → execute → verify → consolidate.

For lower-level CLI automation, `aw create "Add rate limiting to the API"`
creates the task record, but the agent skill owns roadmap association and the
full lifecycle.

### 3. Check status

```bash
aw status
```

See active tasks, their current step, and any open items.

### 4. Launch the dashboard (optional)

```bash
aw dashboard start
```

Starts the opt-in local dashboard service for inspecting task artifacts,
plans, execution notes, and verification results. `aw server start` supervises
core background services but leaves the dashboard disabled unless configured.

## Agent integration

Weyaw works through agent skills — prompts recognized by coding agents
(Claude Code, Codex, etc.) in the project session. The skills are
registered in `.agents/skills/` for current Codex repositories and in
`.claude/skills/` for Claude Code. The explicit `codex` compatibility target
continues to install legacy copies in `.codex/skills/`.

Common skills to use in an agent session:

| Skill | Purpose |
|---|---|
| `$aw-init` | Set up or reconcile project context |
| `$aw` | Inject lightweight workflow context without starting work |
| `$aw-task <intention>` | Start task work from an intention |
| `$aw-resume <task-id>` | Continue a recorded task |
| `$aw-status` | Report workflow state |
| `$aw-health` | Check or repair artifact consistency |
| `$aw-help` | Suggest the next useful action |
| `$aw-goal <item ids>` | Run an ordered roadmap batch serially |

See [Skills](skills.md) for the full reference.

## Next steps

- [Concepts](concepts.md) — Task lifecycle, artifacts, and workflow model
- [CLI](cli.md) — Full command reference
- [Artifacts](artifacts.md) — What lives in `.aw/` and why
- [Dashboard](dashboard.md) — Using the local inspection UI