loopany Documentation

Pages

1. OverviewWhat loopany exposes (CLI, workspace, skills), runtime assumptions (Bun, $LOOPANY_HOME), and the shortest path from init to a running mission-backed brain.
2. InstallationClone the repo, install Bun, link the CLI, set PATH, initialize $LOOPANY_HOME, and wire the resolver injection into Claude Code, Codex, or other agent hosts.
3. QuickstartFirst successful session: init workspace, create a mission and task, add a reference edge, run doctor, and optional reindex/search or factory UI.
4. Artifacts and workspaceOn-disk layout under $LOOPANY_HOME: artifacts/<dirName>/<slug>.md, config.yaml, references.jsonl, audit.jsonl, optional search.db, and v0.2 slug-as-id storage rules.
5. Kinds and validationMarkdown kind definitions, dynamic Zod frontmatter schemas, status machines, indexedFields, slug rules, and immutable write semantics (append, status flip, supersede).
6. Reference graphAppend-only references.jsonl edges, implicit mentions from frontmatter, canonical relation verbs, refs/trace queries, and wiki-link [[id]] conventions.
7. DomainsScope-local packs under domains/<name>/, enabled_domains in config.yaml, domain-scoped kind overrides, and when to propose a domain vs a note.
8. Skills libraryAgent-readable SKILL.md packs (resolver, core, capture, reflect, review), routing table, cross-skill chaining, and harness-neutral memory injection.
9. Self-improvement loopTask ## Outcome evidence, learning beliefs, skill-proposal accept/reject flow, checkAt followups, and the rule that agents never edit skills directly.
10. Workspace setupRun loopany init, verify bundled kinds copied, complete ONBOARDING.md once, register cadence (cron vs session-boundary), and confirm doctor passes.
11. Capture workflowEnd-of-task capture quality gate, event→kind routing (task/signal/note), subagent dispatch pattern, and duplicate detection via artifact list --contains.
12. Reflect workflowGather recent outcomes and dismissed signals, pattern thresholds, write learning and skill-proposal artifacts, and accept/reject proposals with git-backed skill diffs.
13. Periodic reviewDaily followups (--due today), weekly doctor + overdue sweep, monthly mission-drift checks, and closure rules for checkAt-bearing artifacts.
14. Schema migrationschemaVersion vs binary VERSION, SchemaVersionMismatchError recovery, loopany migrate discovery, and v0.1.0→v0.2.0 script-driven workspace transforms.
15. CLI referenceFull command surface from loopany --help: init, artifact/*, refs, trace, domain, followups, search, reindex, factory, kind list, doctor, migrate, and JSON stdout conventions.
16. Artifact commandscreate/get/list/append/status/set flags, per-kind --field validation, --slug and --content-file, journal auto-management, and required ## Outcome on terminal task statuses.
17. Graph, search, and schedulingrefs add/query, trace BFS, followups --due, hybrid search/reindex (--no-embed), factory UI (--port/--no-open), and audit.jsonl side effects.
18. Configuration referenceconfig.yaml keys (schemaVersion, enabled_domains), environment variables LOOPANY_HOME, LOOPANY_SKIP_VERSION_CHECK, LOOPANY_EDITOR, and SCHEMA_VERSION guard behavior.
19. Artifact lifecycle exampleEnd-to-end recipe: signal → task with led-to/addresses edges, status transitions, brief output, and journal linkage—mirroring test/scenario.e2e and skill-regression flows.
20. Self-improvement exampleRecipe: three done tasks with outcomes → reflect writes learning + pending skill-proposal → user accepts → skill file diff and proposal Outcome recorded.
21. Build and testbun install, typecheck, bun test unit/e2e, compiled binary via bun build --compile, and skill-regression.sh requirements (claude CLI, API key).
22. Doctor and troubleshootingdoctor checks (workspace, schema version, kinds, artifacts, references, onboarding), common failures (WorkspaceNotFound, Zod validation, missing search index), and factory/reindex recovery steps.