A

Concepts

CodeAlmanac has five core concepts.

1. Almanac Tree#

Each repository owns one wiki tree at almanac/.

your-repo/
|-- almanac/
|   |-- README.md
|   |-- topics.yaml
|   |-- architecture/
|   |   |-- README.md
|   |   `-- indexing.md
|   |-- decisions/
|   |   `-- local-first.md
|   `-- guides/
|       `-- setup.md
|-- src/
`-- ...

There are no alternate roots.

2. Pages#

A page is a Markdown file under almanac/, except reserved root files such as topics.yaml and local config files.

The page id is its path under almanac/ without .md:

almanac/README.md                         -> README
almanac/architecture/README.md            -> architecture
almanac/architecture/indexing.md          -> architecture/indexing
almanac/guides/setup.md                   -> guides/setup

README.md files are folder landing pages. Route collisions are invalid:

almanac/architecture.md
almanac/architecture/README.md

Those two files both map to architecture, so validation rejects the tree.

3. Topics#

Topics are categories for pages. They live in almanac/topics.yaml.

Topics form a DAG, not a folder tree. A page can have multiple topics, and a topic can have multiple parents.

codealmanac topics
codealmanac topics show systems --descendants
codealmanac search --topic systems

Authored page links use normal Markdown links.

[Indexing](/codealmanac/docs/architecture/indexing)
[Setup guide](/codealmanac/docs/guides/setup)

Structured evidence lives in sources: frontmatter.

---
title: Auth Flow
topics: [systems]
sources:
  - id: auth-session
    type: file
    path: src/auth/session.py
    note: Login checks session state here.
---

File sources power --mentions:

codealmanac search --mentions src/auth/session.py
codealmanac search --mentions src/auth/

5. Local Index And Commands#

Markdown is the source of truth. SQLite is a derived local cache under ~/.codealmanac/.

Query commands refresh the index silently when pages change. codealmanac validate checks the wiki tree, links, sources, runtime state, and derived index. codealmanac reindex forces a full rebuild.

Command groups:

Group Commands AI needed?
Read list, search, show, topics, health, validate, serve No
Organize tag, untag, topics create/rename/delete/link No
Lifecycle init, build, ingest, garden, sync, jobs ingest, garden, and write-capable sync
Admin setup, uninstall, doctor, update, automation, reindex No

Scheduled automation is local scheduler state. It runs ordinary codealmanac sync, codealmanac garden, or codealmanac update --scheduled commands; it is not hosted sync. codealmanac setup --yes installs the default local automation, and codealmanac uninstall removes CodeAlmanac-owned local artifacts without a partial-uninstall mode.