/index

description: "Rebuild the knowledge tag index. Scans promoted files, normalizes tags, flags untagged files, suggests freeform-to-known promotions, detects stale files, suggests cross-references, updates project-to-tag mappings, and regenerates index.md. Use when user says '/index', 'rebuild index', 'update index', 'reindex knowledge'. Also called automatically by /audit knowledge. (Code port — ADR-094.)"

/index — Knowledge Index Builder

Scan all promoted knowledge files, normalize tags, detect issues, and regenerate `{knowledge_folder}/index.md`.

Step 0: Resolve Config

Read `~/.gemini/antigravity/aria-knowledge.local.md` and extract:

• `knowledge_folder` — base path for all operations
• `freeform_promotion_threshold` — minimum file count before suggesting promotion (default: 3)
• `staleness_threshold_months` — months before a file is flagged stale (default: 6)
• `projects_enabled` — default `false`; controls whether project tier is scanned and indexed
• `projects_list` — default empty; comma-separated `tag:path` pairs; only relevant if `projects_enabled: true`
• `projects_promotion_threshold` — default `2`; minimum projects sharing a similar pattern to surface as a cross-project promotion candidate
• `projects_shared_knowledge` — default empty; comma-separated list of project tags enabled for shared knowledge. When non-empty, scan each listed project's `_project-knowledge/` folder for team-shared knowledge. Tags not in this list are skipped (their `_project-knowledge/` folders, if any exist on disk, are NOT indexed).

If the config file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."

Step 1: Scan Promoted Folders

Scan these directories for `.md` files (excluding directory README stubs that only contain a few lines of boilerplate):

• `{knowledge_folder}/approaches/`
• `{knowledge_folder}/decisions/`
• `{knowledge_folder}/guides/` (recursive — includes subdirectories)
• `{knowledge_folder}/references/` (recursive — includes `sources/` and other subdirectories)

**Do NOT scan:** `archive/`, `intake/`, `rules/`, top-level `logs/*.md` (audit-log files like `config-audit-log.md`, `knowledge-audit-log.md`, `hook-debug.log`), or root-level files (`README.md`, `LOCAL.md`, `OVERVIEW.md`, `index.md`).

**Carve-out for review reports:** the two subfolders `logs/prospect/` and `logs/retrospect/` ARE scanned as a separate "reviews tier" — see the dedicated sub-step below. Review reports use the same frontmatter scanning convention as cross-project files (tags, Last updated, first heading).

For each `.md` file found: 1. Read the file 2. Extract YAML frontmatter (content between `---` markers at the top of the file) 3. From frontmatter, extract:

• `tags:` — array of tags (e.g., `tags: [api, pagination, django]`). If missing, record as untagged.
• `Last updated:` — date string (YYYY-MM-DD). If missing, record as unknown.
• `semantic-hints:` — array of free-form phrases (e.g., `semantic-hints: [cursor pagination, keyset pagination]`). Optional; if missing, treat as empty list. Added 2.16.0.

4. Extract the first `#` heading as the file's description 5. Store: `{path, tags[], hints[], description, last_updated, source: "cross-project"}`

Report: "Scanned N files in approaches/, decisions/, guides/, references/."

Reviews tier scan (always run if either review subfolder exists)

After the cross-project scan, scan `logs/prospect/` and `logs/retrospect/` for review reports written by the `/prospect` and `/retrospect` skills.

For each `.md` file found in either subfolder: 1. Read the file 2. Extract YAML frontmatter — review reports have a richer schema than cross-project files. Pull:

• `tags:` — array of tags. Always includes `prospect` or `retrospect` plus the scope keyword. If missing (legacy reports written before the structured-frontmatter format), record as untagged and emit a soft warning (one-line) suggesting the file be re-run or hand-tagged.
• `Last updated:` — fall back to `date:` if `Last updated:` is absent (review reports use `date:` for the report-creation date).
• `type:` — `prospect` or `retrospect`. Used to bucket the file under "Retrospects" or "Prospects" in the `## Review Index` section of `index.md` (see Step 9).
• `scope:` — the scope keyword (e.g., `release`, `deployment`, `commit`, `plan`).
• `tickets:` — for cross-reference enrichment (consumed by `/context`).

3. Extract the first `#` heading as the file's description (typically "/prospect — <goal>" or "/retrospect — <goal>"). 4. Store: `{path, tags[], description, last_updated, source: "review", review_type: <prospect|retrospect>, scope: <keyword>, tickets: [...]}`

Report: "Scanned R review reports across logs/prospect/ and logs/retrospect/ (P prospect, Q retrospect)."

If neither subfolder exists yet on disk, skip this sub-step silently (first run before any /prospect or /retrospect has been invoked).

Project tier scan (only if `projects_enabled: true` and `projects_list` is non-empty)

After the cross-project scan, scan the project tier:

For each `tag:path` pair in `projects_list`: 1. Glob `{knowledge_folder}/projects/{tag}/**/*.md` recursively 2. **Exclude** `projects/{tag}/README.md` (per-project navigation, not knowledge content) 3. **Exclude** `projects/README.md` (the projects/ tier README, plugin-managed) 4. For each file found, perform the same frontmatter extraction as above. 5. **Path-derived tag union (Decision #9):** automatically add `{tag}` to the file's tag set even if not in YAML frontmatter. The union of YAML tags + path tag is what gets indexed. This means project files don't have to manually include the project tag in their frontmatter. 6. Store: `{path, tags[], description, last_updated, source: "project-specific", project: tag}`

Report: "Scanned M files across N project subdirectories: [project tags]."

If `projects_enabled: false` or `projects_list` is empty, skip this sub-step entirely. Project tier files (if any exi