# amduat-app-next (Scaffold)

Starter project scaffold for building an app against `amduatd` v2.

## Included handoff assets

- `docs/v2-app-developer-guide.md` (compact app guide)
- `contracts/amduatd-api-contract.v2.json` (machine contract)
- `scripts/graph_client_helpers.sh` (reusable shell helpers)

## Quick start

1. Configure environment:

```sh
cp config/env.example config/env.local
```

2. Start a local daemon:

```sh
./scripts/dev_start_daemon.sh
```
`dev_start_daemon.sh` initializes the store for the selected backend and, when
`STORE_BACKEND=index`, runs a quick startup write probe. If index writes are
unhealthy, it automatically falls back to `fs` (configurable via
`INDEX_BACKEND_PROBE` and `INDEX_BACKEND_FALLBACK` in `config/env.local`).

3. Run startup checks against the daemon socket:

```sh
./scripts/bootstrap_check.sh
```

4. Run sample idempotent batch ingest:

```sh
./scripts/ingest_example.sh
```

5. Run sample changes sync loop:

```sh
./scripts/sync_loop.sh
```

## v2 Vertical Slice CLI

Use the integrated v2 app flow wrapper:

```sh
./scripts/v2_app.sh startup-check
./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc-1"}]}'
./scripts/v2_app.sh sync-once
./scripts/v2_app.sh retrieve 'doc-1' 'ms.within_domain'
./scripts/v2_app.sh tombstone '<edge_ref>'
```

Run integration coverage (requires running `amduatd` + `jq`):

```sh
./tests/integration_v2.sh
```

Run a fast end-to-end smoke (startup + ingest + sync + retrieve + tombstone):

```sh
./scripts/smoke_v2.sh
```

## Notes

- This scaffold assumes local Unix-socket access to `amduatd`.
- Graph cursors are opaque and must be persisted exactly as returned.
- Keep `contracts/amduatd-api-contract.v2.json` in sync with upstream when you pull updates.