# Quickstart

> First successful session: init workspace, create a mission and task, add a reference edge, run doctor, and optional reindex/search or factory UI.

- Repository: superdesigndev/loopany
- GitHub: https://github.com/superdesigndev/loopany
- Human docs: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8
- Complete Markdown: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8/llms-full.txt

## Source Files

- `src/cli.ts`
- `src/commands/init.ts`
- `src/commands/artifact-create.ts`
- `src/commands/doctor.ts`
- `skills/loopany-core/kinds/mission.md`
- `skills/loopany-core/kinds/task.md`
- `test/scenario.e2e.test.ts`

---

---
title: "Quickstart"
description: "First successful session: init workspace, create a mission and task, add a reference edge, run doctor, and optional reindex/search or factory UI."
---

`loopany init` scaffolds a workspace at `$LOOPANY_HOME` (default `~/loopany`), copies bundled kind definitions from `skills/loopany-core/kinds/`, and writes `config.yaml` with the current `schemaVersion`. Every other command in this guide assumes that workspace exists and that at least one `mission` with `status: active` plus a `self` person artifact are present — without them, `loopany doctor` fails the onboarding check and `init` prints a pointer to `ONBOARDING.md`.

## Prerequisites

| Requirement | Notes |
|-------------|-------|
| [Bun](https://bun.sh) | Runtime for `src/cli.ts` and tests |
| `loopany` on `PATH` | From repo: `bun install` then `bun link`, or `bun run src/cli.ts` |
| Writable `$LOOPANY_HOME` | Override with `export LOOPANY_HOME=/path/to/workspace` for isolated runs |

<Note>
CLI commands that mutate or query artifacts print **JSON on stdout** (one object or array). Human-readable text appears only for `init`, `doctor` (default format), `factory`, and `--help`.
</Note>

## Session overview

```mermaid
sequenceDiagram
  participant You
  participant CLI as loopany CLI
  participant WS as $LOOPANY_HOME
  participant Graph as references.jsonl

  You->>CLI: init
  CLI->>WS: kinds/, artifacts/, config.yaml
  You->>CLI: artifact create (person, mission, task)
  CLI->>WS: artifacts/people/self.md, missions/*.md, tasks/*.md
  You->>CLI: refs add
  CLI->>Graph: append edge
  You->>CLI: doctor
  CLI->>WS: validate kinds, artifacts, graph, onboarding
  opt Search / UI
    You->>CLI: reindex
    CLI->>WS: search.db
    You->>CLI: search / factory
  end
```

After a successful pass, the workspace holds markdown artifacts under `artifacts/<dirName>/<id>.md`, hard edges in `references.jsonl`, and operational lines in `audit.jsonl`.

## Initialize the workspace

<Steps>
<Step title="Run init">

```bash
loopany init
```

Creates (if missing): workspace root, `kinds/`, `artifacts/`, and `config.yaml` with `schemaVersion` matching the binary. Copies any bundled `*.md` kind files not already present in `kinds/`.

<RequestExample>

```bash
loopany init
```

</RequestExample>

<ResponseExample>

```text
Initialized loopany workspace at /Users/you/loopany
Created 12 file(s).

NEXT — read ONBOARDING.md and start the onboarding conversation.
Without an active mission artifact, the brain has no reason to exist.
```

</ResponseExample>

The onboarding hint appears when `artifacts/missions/` has no `.md` files yet. Re-running `init` is idempotent — existing files are left untouched.

</Step>
<Step title="Confirm layout">

```text
$LOOPANY_HOME/
  config.yaml
  kinds/           # mission.md, task.md, person.md, …
  artifacts/       # empty until you create artifacts
  audit.jsonl      # written after first mutating command
```

Bundled kinds after init include: `brief`, `journal`, `learning`, `mission`, `note`, `person`, `signal`, `skill-proposal`, `task`.

</Step>
</Steps>

For a disposable workspace (matches e2e tests):

```bash
export LOOPANY_HOME="$(mktemp -d)"
loopany init
```

## Minimum viable brain

Doctor’s **onboarding** check requires:

1. A `person` artifact with id `self`
2. At least one `mission` with `status: active`

<Steps>
<Step title="Create self">

```bash
loopany artifact create \
  --kind person \
  --slug self \
  --name "Your Name"
```

<ResponseField name="stdout" type="object">
JSON with `id`, `kind`, `path`. For `--slug self`, `id` is `self` and the file is `artifacts/people/self.md`.
</ResponseField>

</Step>
<Step title="Create an active mission">

```bash
loopany artifact create \
  --kind mission \
  --slug ship-v1 \
  --title "Ship loopany v1" \
  --status active \
  --hypothesis "Dogfood CLI daily and fix friction as it appears"
```

Required frontmatter for `mission`: `title` (string), `status` (`active` | `paused` | `satisfied` | `abandoned`). Optional: `hypothesis`, `domain`.

Mission files live at `artifacts/missions/<slug>.md`. The slug becomes the global artifact id used in `refs`, `mentions`, and `[[wiki-links]]`.

</Step>
<Step title="Create a task linked to the mission">

```bash
loopany artifact create \
  --kind task \
  --slug quickstart-smoke \
  --title "Verify loopany quickstart path" \
  --status todo \
  --priority medium \
  --mentions ship-v1
```

`task` defaults `status` to `todo` if omitted. `mentions` is a comma-separated list of artifact ids (here, the mission slug).

</Step>
</Steps>

<ParamField body="--slug" type="string">
Stable id for citations. Omitted: derived from `--title` with collision suffixes, or a time-based slug when no title is usable.
</ParamField>

<ParamField body="--content / --content-file" type="string">
Optional markdown body at create time. Use `--content-file -` to read stdin.
</ParamField>

Field flags are per-kind. Unknown flags produce an error listing valid fields for that kind (see `~/loopany/kinds/<kind>.md` or `loopany kind list`).

## Add a reference edge

Hard graph edges are append-only records in `references.jsonl`, written by the CLI (not by editing artifact bodies alone).

Link a task to the mission with an explicit edge (in addition to `mentions` in frontmatter, which the index also treats as soft links):

```bash
loopany refs add \
  --from quickstart-smoke \
  --to ship-v1 \
  --relation mentions
```

<ResponseExample>

```json
{
  "from": "quickstart-smoke",
  "to": "ship-v1",
  "relation": "mentions",
  "ts": "2026-06-05T12:00:00.000Z",
  "actor": "cli"
}
```

</ResponseExample>

Query outgoing edges:

```bash
loopany refs quickstart-smoke
```

Common relations (open registry; these are conventions): `led-to`, `addresses`, `mentions`, `supersedes`, `follows-up`, `cites`. See the relations convention skill for direction rules — e.g. `led-to` runs **from** cause **to** effect (`signal` → `task`).

## Verify with doctor

```bash
loopany doctor
```

Exit code `0` only when no check has status `fail`. Typical human output:

```text
Workspace       /Users/you/loopany ✓
Schema version  v0.2.0 ✓
Kinds           9 loaded (brief, journal, …) ✓
Artifacts       3 total, all valid ✓
References      1 edges, no dangling ✓
Onboarding      self present, 1 active mission(s) ✓
Mission coverage all tasks mention a mission ✓
Domain coverage enabled: [none] ✓
```

| Check | Fail vs warn |
|-------|----------------|
| `workspace`, `schema version`, `kinds`, `artifacts`, `references`, `onboarding` | **fail** — fix before relying on the brain |
| `mission coverage` | **warn** — tasks without `mentions` pointing at a mission id |
| `domain coverage` | **warn** — artifact `domain` not in `enabled_domains` |

JSON report:

```bash
loopany doctor --format json
```

Doctor runs with schema version check bypassed so it can **report** mismatches and suggest `loopany migrate …` instead of crashing.

<Warning>
A fresh `init` workspace fails onboarding until `self` and an active `mission` exist. That is expected — not a broken install.
</Warning>

## Optional: search and factory

### Hybrid search

Search uses a derived SQLite index at `$LOOPANY_HOME/search.db`. Creates and appends do **not** auto-update the index; run `reindex` after bulk writes or when search feels stale.

```bash
loopany reindex --no-embed    # fast CI-style index; keyword FTS only
loopany reindex               # full index with embeddings (first run loads model)
loopany search "quickstart" --kind task --limit 5
```

If `search.db` is missing, `loopany search` returns `[]` and prints on stderr: `no search index found — run loopany reindex first.`

| Flag | Effect |
|------|--------|
| `--force` | Delete and rebuild `search.db` |
| `--no-embed` | Skip embedding model; FTS keyword path only |

### Factory UI

Read-only walkable view of the workspace:

```bash
loopany factory --port 4242 --no-open
```

Defaults: host `127.0.0.1`, port `4242`, opens browser on macOS/Windows/Linux unless `--no-open`. Ctrl-C stops the server.

## Complete copy-paste script

Sets `LOOPANY_HOME` to a temp dir, runs the full minimal path, and leaves doctor green:

```bash
export LOOPANY_HOME="$(mktemp -d)"
loopany init

loopany artifact create --kind person --slug self --name "Quickstart User"
loopany artifact create \
  --kind mission --slug ship-v1 \
  --title "Ship loopany v1" --status active
loopany artifact create \
  --kind task --slug quickstart-smoke \
  --title "Verify loopany quickstart path" \
  --status todo --mentions ship-v1

loopany refs add --from quickstart-smoke --to ship-v1 --relation mentions
loopany doctor
```

Inspect artifacts:

```bash
loopany artifact get ship-v1
loopany artifact list --kind task --status todo
```

## Agent-led onboarding

If you use an agent harness instead of hand-typing commands, point it at `ONBOARDING.md` after `init`. That script creates `self`, one or more active missions, and optional backfill artifacts — the same end state this quickstart builds manually. Do not run onboarding twice when an active mission already exists.

## Troubleshooting

| Symptom | Likely cause | Action |
|---------|----------------|--------|
| `Error: … run loopany init` | `$LOOPANY_HOME` missing or empty | `loopany init` or set `LOOPANY_HOME` |
| `Invalid input:` + Zod paths | Wrong `--field` for kind | `loopany kind list`; read `kinds/<kind>.md` |
| Doctor onboarding ✗ | No `self` or no active mission | Create artifacts above |
| Doctor schema version ✗ | Workspace older than binary | `loopany migrate` (see migration docs) |
| `Unknown field for kind X` | Typo in flag name | Use `--check-at` not `--checkAt` (kebab-case flags) |
| Search always empty | No index | `loopany reindex` |
| `refs add` error | Missing `--from` / `--to` / `--relation` | All three required |

<Info>
`LOOPANY_SKIP_VERSION_CHECK=1` bypasses the schema guard for emergency inspection; prefer `loopany migrate` for real version drift.
</Info>

## What you have now

```text
artifacts/
  people/self.md
  missions/ship-v1.md
  tasks/quickstart-smoke.md
references.jsonl    # mentions edge(s)
audit.jsonl         # init, creates, refs, doctor ops
config.yaml         # schemaVersion, enabled_domains (when set)
```

Next operational steps (not required for “first success”): complete a task with `artifact append --section Outcome` then `artifact status <id> done`, run `loopany followups --due today` when `checkAt` is set, or wire the resolver skill into your agent host per the installation page.

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Clone, link the CLI, set `PATH` and `$LOOPANY_HOME`, and attach the resolver to your agent host.
</Card>
<Card title="Artifacts and workspace" href="/artifacts-and-workspace">
On-disk layout, slug-as-id rules, and immutable write semantics.
</Card>
<Card title="Reference graph" href="/reference-graph">
Relation verbs, `refs`/`trace` queries, and wiki-link conventions.
</Card>
<Card title="Artifact lifecycle example" href="/artifact-lifecycle-example">
Signal → task → outcome flow aligned with `test/scenario.e2e.test.ts`.
</Card>
<Card title="Doctor and troubleshooting" href="/doctor-and-troubleshooting">
Full check list, JSON format, and recovery patterns.
</Card>
<Card title="CLI reference" href="/cli-reference">
Complete command surface and stdout conventions.
</Card>
</CardGroup>