# Onboarding

Use this guide to become productive in your first two hours without breaking release flow or tracker integrity.

## Agent Quick Context

- Bootstrap with `npm install -g .`, verify toolchain versions, then run `pnpm build`.
- Use `pm context` + `pm search` before creating any new item.
- Claim before substantial edits and link files/docs/tests as you go.
- Run sandbox-safe tests before closing items.
- Never hand-edit tracker records or generated changelog output.

Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5h](../.agents/pm/tasks/pm-oh5h.toon), [pm-10ml](../.agents/pm/stories/pm-10ml.toon).

## Prerequisites

- Node.js 20 or newer
- pnpm 10 or newer
- Git + GitHub CLI (`gh`) authenticated for this repository

## First-Time Bootstrap (Real Repository Work)

Run from the repository root:

```bash
npm install -g .
pm --version
node -v
pnpm -v
pnpm build
export PM_AUTHOR="<stable-agent-id>"
```

For real repository tracking, do not set `PM_PATH`.

## First Read Path

Use progressive disclosure:

```bash
pm context --limit 10
pm search "<request keywords>" --limit 10
pm list-open --limit 20
pm list-in-progress --limit 20
pm install guide-shell --project
pm guide workflows
```

Then use:

- [Agent Guide](AGENT_GUIDE.md)
- [Command Reference](COMMANDS.md)
- [Testing](TESTING.md)
- [Releasing](RELEASING.md)

## Safe Local Verification

Use sandbox-safe wrappers for test execution:

```bash
node scripts/run-tests.mjs test
node scripts/run-tests.mjs coverage
```

Standard local gate set:

```bash
pnpm build
pnpm typecheck
node scripts/run-tests.mjs coverage
pnpm quality:docs-skills
pm validate --check-resolution --check-history-drift
```

## Real Tracker Workflow (Canonical Loop)

1) Orient and dedupe

```bash
pm context --limit 10
pm search "<keywords>" --limit 10
pm list-open --limit 20
pm list-in-progress --limit 20
```

2) Claim and start

```bash
pm claim <id>
pm update <id> --status in_progress --message "Start implementation"
```

3) Link execution context while editing

```bash
pm files <id> --add path=src/...,scope=project,note="implementation scope"
pm docs <id> --add path=docs/...,scope=project,note="user-facing behavior"
pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/...",scope=project,timeout_seconds=240
```

4) Record progress

```bash
pm comments <id> "Progress update and rationale."
pm notes <id> --add "Design tradeoff."
pm learnings <id> --add "Durable lesson."
```

5) Verify, close, and release

```bash
pm test <id> --run --progress
pm comments <id> "Evidence: linked tests and gates passed."
pm close <id> "Acceptance criteria met; verification passed." --validate-close warn
pm release <id>
```

## Release Overview

- Daily release prep runs via `.github/workflows/auto-release.yml`.
- Tag-triggered publish runs via `.github/workflows/release.yml`.
- `CHANGELOG.md` is generated by `pm-changelog` and must stay package-generated.

Local parity:

```bash
pnpm release:pipeline:dry-run
pnpm release:pipeline
```

## Hard Never-Do List

- Do not hand-edit `CHANGELOG.md` (use `pnpm changelog:pm` only).
- Do not run manual `npm publish` for this project.
- Do not set `PM_PATH` for real repository mutations.
- Do not edit `.agents/pm/**` files directly; mutate through `pm` commands.
- Do not bypass governance with destructive git commands unless explicitly approved.

## Diagnostics and Recovery

```bash
pm health --check-only
pm validate --check-resolution --check-history-drift
pm normalize --dry-run --json
pm package doctor --project --detail summary
pm contracts --command <command> --flags-only --json
```

If history drift is reported:

```bash
pm history-repair <id> --dry-run
pm history-repair <id>
```

If sensitive content is found in history:

```bash
pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run
pm history-redact <id> --literal "<secret>" --replacement "[redacted]"
```

## Private Operations Boundary

Keep credentials, host-specific runbooks, internal topology, and raw private reliability logs out of tracked docs and package output. Keep those details in local, ignored operations notes.