All OpenCues documentation lives in the GitHub repo, split into two trees with different jobs: docs/ explains the reference implementation, and spec/ defines the open standard any implementation can target. This FAQ is the third layer: task-shaped answers that link into both.
The docs/ tree: how the reference implementation works
docs/overview.md: system layers, core interfaces, and API usage in one read. Start here if you want the architecture.docs/glossary.md: every term (cues, blanks, sources, parsers, the config files) defined in one place.docs/features/: one file per feature concept, around forty of them, fromnavigation.mdandcycling.mdtoidentity-context.mdandsentence-cues.md. Each is short and self-contained.docs/guides/: task-oriented how-tos:quickstart.md,cli-reference.md,llm-providers.md, plus the extension guides (adding-a-feature.md,adding-an-integration.md,adding-a-cue-blank.md).docs/configuration.md: the settings file and LLM routing, end to end.docs/prompt-design-learnings.md: the prompt-engineering principles behind the shipped prompts, useful when writing your own cues.
The spec/ tree: the open standard
If you're implementing OpenCues in another editor rather than using it, spec/ is your contract: core.md for discovery and the master files, cue-spec.md, blank-spec.md, and identity-context-spec.md for each format, JSON Schemas under spec/schemas/, an executable conformance suite under spec/conformance/, and a proposal process under spec/proposals/. The standard has its own CHANGELOG.md and SECURITY.md, and it versions independently of the runtime, because wire-format changes and implementation fixes move at different speeds. A useful property of the split: a second implementation only needs spec/; nothing normative hides in docs/.
Quick routing table
| You want to | Read |
|---|---|
| Install and try it | Repo README.md, then docs/guides/quickstart.md |
| Understand a term | docs/glossary.md |
| Look up one feature | docs/features/<name>.md |
| Use the CLI | docs/guides/cli-reference.md |
| Fix something broken | Repo FAQ.md, or OpenCues not working? |
| Write your own configs | Write a cue / blank |
| Implement the standard | spec/, starting at spec/README.md |
Two trees the map often misses
The repo's own docs README draws a distinction worth repeating: docs/features/ answers "what does this do" (platform-agnostic, short, one concept per numbered file), while docs/architecture/ answers "why is it built this way, and what breaks if I change it" (deep implementation references, aimed at contributors). If you're using OpenCues, you'll live in features and guides; if you're changing it, architecture is mandatory reading. There's also a root-level FAQ.md in the repo itself, covering install paths, uninstall behaviour, and debugging, and docs/benchmarks/ holds dated benchmark write-ups whose live numbers sit in tests/benchmarks/.
And this site
The FAQ hub holds a hundred-plus task-shaped answers, the open standard page summarises the spec, and the changelog tracks releases. The repo docs are the source of truth; when this site and the repo disagree, trust the repo and tell us.
Related: Release notes · CLI reference · How to contribute · GitHub repo