Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

Canonry Docs Index

Start here when you need to understand what is implemented today, what is planned next, and which architectural decisions are already settled.

Canonry is API-first. The API is the source of truth, the CLI is the standard operator surface, and the web UI is a secondary consumer for human analysts.

Repo Narrative Docs

Document Label Audience Purpose
README.md current users, operators Product overview, quickstart, key CLI/API entrypoints
CONTRIBUTING.md current contributors Setup, workspace structure, and contribution rules
AGENTS.md current Codex, Claude Code Repo guidance optimized for Codex and Claude Code
CLAUDE.md current Claude Code Claude-specific overlay (imports AGENTS.md + UI design system)

Current Reference And Guides

Document Label Audience Purpose
architecture.md current engineers System architecture, dependency graph, run lifecycle, provider system
data-model.md current engineers ER diagram, table groups, JSON column shapes
deployment.md current operators Current deployment and runtime guidance
testing.md current contributors Validation and test workflow guidance
mcp.md current operators, agent users, contributors MCP stdio adapter rationale, setup, auth model, safety rules, and limitations
providers/README.md current engineers Provider system overview, ProviderAdapter interface, how to add a provider
providers/gemini.md current engineers Gemini provider behavior and constraints
providers/openai.md current engineers OpenAI provider behavior and constraints
providers/claude.md current engineers Claude provider behavior and constraints
providers/local.md current engineers Local provider behavior and constraints
providers/perplexity.md current engineers Perplexity provider behavior and constraints
google-search-console-setup.md current operators Google Search Console OAuth setup and usage
bing-webmaster-setup.md current operators Bing Webmaster Tools API key setup and usage
google-analytics-setup.md current operators Google Analytics 4 service account setup and usage
wordpress-setup.md current operators WordPress REST + Application Password setup, staging diffs, and manual handoff workflows

Product Direction

Document Label Audience Purpose
roadmap.md roadmap founders, maintainers Canonical product roadmap and prioritization
gtm.md launch plan founders, maintainers GTM launch sequencing, success metrics, per-agent distribution

docs/roadmap.md is the canonical product roadmap (feature-level priority). docs/gtm.md is the launch view (waves, ship gates, distribution). Do not treat plans or ADRs as substitutes for either.

Active Plans

Document Label Audience Purpose
../plans/deployment-parity.md active plan engineers, operators Bring local, Docker, and hosted deployment paths into parity
../plans/optimize-ai-calls.md active plan engineers Reduce provider cost and unnecessary repeat calls
../plans/gbp-phase-3-4-handoff.md active plan engineers Google Business Profile next steps — Phase 3 (web UI) + Phase 4 (scheduling, doctor checks, insights)

Plans describe implementation work. They are not current-behavior reference docs.

ADR Index

ADR Label Purpose
0001-root-package-workspace.md ADR Keep @ainyc/aeo-audit as an external dependency
0002-separate-score-families.md ADR Keep technical readiness and answer visibility as separate score families
0003-provider-throttling-and-quotas.md ADR Use conservative provider throttling and quota defaults
0004-local-llm-provider.md ADR Support local LLMs via an OpenAI-compatible provider
0005-distributed-node-hub-architecture.md ADR Define the long-term distributed node and hub architecture
0006-location-aware-tracking.md ADR (superseded) Historical proposal for query-scoped location tracking
0007-project-scoped-location-context.md ADR Keep locations project-scoped and use them as run context
0008-canonry-package-split.md ADR Split @ainyc/canonry into smaller publishable packages
0009-content-action-outcome-ledger-and-publish-boundary.md ADR Content action outcome ledger + publish transformer/adapter boundary
0010-openai-web-search-tool.md ADR Use OpenAI's GA web_search tool over legacy web_search_preview; keep its new knobs off

Reading Order

  1. Read README.md for product context and quickstart.
  2. Read architecture.md for the current shape of the system.
  3. Read roadmap.md for feature-level product direction and gtm.md for the launch view.
  4. Use the provider, deployment, and testing docs for current implementation details.
  5. Read ADRs when you need durable architectural rationale.