Imported from arcanewords-app/arcane-reader (
AGENTS.md). Install upstream withnpx skills add arcanewords-app/arcane-reader. Copyright stays with the author.
Arcane Reader — Agent Instructions
Navigation map for AI agents. Policies and architecture live in .cursor/rules/ (loaded automatically); do not duplicate them here.
Start here
| Need | Where |
|---|---|
| Which agent owns the task | .cursor/rules/team-orchestrator.mdc (agent-requested when implementing) |
| Code style, PR checklist | .cursor/rules/core.mdc |
| Module map, data flow | .cursor/rules/architecture.mdc |
| Route map (SSOT) | .cursor/rules/routing.mdc |
| Security policies | .cursor/rules/security.mdc + .cursor/skills/security/SKILL.md |
| Supabase SQL migrations | .cursor/rules/supabase.mdc — only supabase/migrations/ (gitignored); history in supabase/README.md |
| All domain rules | .cursor/rules/ |
| Local dev, vault, grep | .cursor/skills/local-dev/SKILL.md |
| UI patterns & UX recipes | .cursor/skills/ui/PATTERNS.md — filters, chips, toolbars |
| News posts, announcements | .cursor/skills/news-content/SKILL.md — technical-startup voice |
| Obsidian vault (MCP) | .cursor/skills/obsidian-mcp/SKILL.md — Obsidian must be running |
| Trello boards (MCP) | .cursor/skills/trello-mcp/SKILL.md — credentials in ~/.cursor/mcp.json |
| Prod/staging logs (MCP) | .cursor/skills/axiom-mcp/SKILL.md — OAuth via official Axiom MCP |
| Local dev debug (curl) | .cursor/skills/debug-local/SKILL.md — /api/debug/query on localhost:3000 |
| npm audit, deps, Node | .cursor/skills/dependency-maintenance/SKILL.md — CVE triage, phased updates |
| Unit / component / integration / contract / gaps | .cursor/skills/testing/SKILL.md + .cursor/rules/testing.mdc |
Workflow: orchestrator → read active .cursor/agents/<domain>/AGENT.md + .cursor/skills/<domain>/SKILL.md → follow domain .mdc rules.
Nested context: src/client/AGENTS.md, src/engine/AGENTS.md, docs/AGENTS.md (Obsidian vault).
Utility subagents (not domain team): devtools.md (Windows VM: search/files/npm — invoke when shell commands fail or repeat), dependency-audit.md (npm audit, outdated, CVE response — see dependency-maintenance skill), testing (.cursor/agents/testing/AGENT.md — Q3 pyramid, coverage, gaps, test infra), seo (.cursor/agents/seo/AGENT.md — audits, GSC, publication SEO), news-content (.cursor/agents/news-content/AGENT.md — /news posts and banners), verifier.md, debugger.md, supabase-docs-setup.md, obsidian-mcp-setup.md, trello-mcp-setup.md, axiom-mcp-setup.md in .cursor/agents/.
Session anchors
For large or multi-step work, attach at session start:
@docs/ROADMAP.md
@docs/project-status.md
Human vault (plans, ADR): docs/Home.md — not agent SSOT. Prefer code + .cursor/rules/ over docs/archive/.
Truth hierarchy
src/— behavior.cursor/rules/— conventions and policiesdocs/vault — plans and how-todocs/archive/— legacy; may be stale
Commands
Quick reference — full cheat sheet: .cursor/skills/local-dev/SKILL.md.
npm run dev # API + client
npm run dev:full # + BullMQ worker
npm run lint:all # lint + typecheck
npm run test # Vitest unit (scripts/test-unit.mjs; pin 5.0.0)
npm run test:component # Testing Library + happy-dom
npm run test:integration # mock-integration (createApp + supertest)
npm run test:contract # Zod contract fixtures
npm run test:coverage # coverage with floors (lines 77 / branches 65); GitHub Actions, not pre-push
npm run test:gaps # component + contract blind spots (advisory); not in pre-push
npm run test:e2e # Playwright logic smoke (not pre-push / Actions; needs stack:up + dev)
npm run test:e2e:visual # pixel shells `@visual` (dirty stamp → stack:restore, not load)
npm run test:e2e:llm # smoke + live OpenAI `@llm`Pre-push: lint:all + test + test:component + test:integration + test:contract.
GitHub Actions: same pyramid with test:coverage instead of test (no Playwright).
Strategy (pyramid): docs/05-plans/testing-strategy.md.
Supabase Docs
Before Supabase work, use live docs via SSH (see .cursor/skills/supabase-docs/SKILL.md):
ssh supabase.sh grep -rl 'auth' /supabase/docs/
ssh supabase.sh cat /supabase/docs/guides/auth/passwords.md