/context

description: "Load relevant knowledge by topic. Queries the tag index and presents matching promoted files for selective loading into context. Use when user says '/context stripe', '/context api pagination', '/context ss', 'load knowledge about...', 'what do we know about...'. (Code port — ADR-094.)"

/context — On-Demand Knowledge Retrieval

Query the knowledge tag index and load relevant promoted files into the conversation context.

Step 0: Resolve Config

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

• `knowledge_folder` — required
• `projects_enabled` — default `false`
• `projects_list` — default empty (only relevant if `projects_enabled: true`)
• `projects_shared_knowledge` — default empty; comma-separated list of project tags enabled for shared knowledge. When non-empty, also surface team-shared files indexed under `## Team-Shared Tag Index`. Tags not in this list are not surfaced even if they appear in the index.

Parse `projects_list` into a tag→path map. The format is comma-separated `tag:path` pairs (e.g., `proj-a:path/to/proj-a,proj-b:proj-b`). Tags are used to identify project-specific files; paths are not used by `/context` (they're for CWD detection in other skills).

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

Step 1: Read Index

Read `{knowledge_folder}/index.md`.

If the file doesn't exist, stop: "No knowledge index found. Run `/index` to build it."

Parse the index to extract:

• `## Projects` section — project name/key and their relevant tags
• `## Known Tags` section — the canonical tag list
• `## Tag Index` section — tag → file mappings for known tags
• `## Other Tags` section — tag → file mappings for freeform tags
• `## Team-Shared Tag Index` section — tag → team-shared file mappings (only when `projects_shared_knowledge` is a non-empty list); paths are absolute-from-home (`~/Projects/...`) and entries carry a `[project: ..., scope: ...]` annotation. Section may be absent if no team-shared files exist or the list is empty.

Step 2: Parse Query

The user's argument is a space-separated list of tags with optional `AND` keyword.

**Parsing rules:**

• Split on spaces
• If the token `AND` (case-insensitive) appears, use **intersection mode** — a file must have ALL specified tags
• Otherwise, use **union mode** (default) — a file matches if it has ANY of the specified tags
• Remove `AND` tokens from the tag list

Examples:

• `/context stripe` → tags: [`stripe`], mode: OR
• `/context api pagination` → tags: [`api`, `pagination`], mode: OR
• `/context api AND pagination` → tags: [`api`, `pagination`], mode: AND
• `/context ss` → tags: [`ss`], mode: OR (with project expansion)

If no argument provided, stop: "Usage: `/context <tag1> [tag2] [AND tag3]`. Run `/index` to see available tags."

Step 2.5: Resolve Aliases (added 2.16.0)

After parsing the query into tokens (Step 2) but BEFORE project expansion (Step 3), resolve any aliases.

**Source:** the alias map is encoded in `index.md`'s `## Known Tags` section as `[aliases: ...]` annotations on canonical tag entries. Parse that section to build a flat `alias → canonical` map. If no aliases are declared (no `[aliases: ...]` annotations exist), skip this step entirely.

**Resolution:** for each token `t` in the parsed query, look up `t` in the alias→canonical map. If matched, replace `t` with its canonical form. Record the resolution.

**Notification:** for each resolution, emit one line BEFORE the Step 3 "Expanded …" notification:

Resolved `rn` → `react-native`

**Order matters:** alias resolution runs BEFORE project expansion. If `seer → ss` is an alias and `ss` is a project tag, querying `/context seer` resolves to `ss` first; Step 3 then expands `ss` to its relevant tags.

**Unidirectional:** resolution is alias → canonical only. Querying the canonical does NOT match alias-only declarations (i.e., querying `react-native` won't surface files that only declare alias `rn`).

Step 3: Project Tag Expansion

For each tag in the query, check if it matches a project key in the `## Projects` section (e.g., `ss`, `cs`, `df`, `aria`).

If a tag matches a project: 1. Keep the project tag itself in the search 2. Also add all of that project's "Relevant tags" to the search 3. Notify the user:

   Expanded `ss` to include: api, django, nextjs, stripe, supabase, database, deployment

Project expansion only applies in union (OR) mode. In AND mode, project tags are treated as literal tags (a file must be tagged `ss` specifically).

Step 4: Match Files

File discovery has three sources: the index `## Tag Index` and `## Other Tags` sections (cross-project tagged files), the filesystem (project-specific files under `projects/{tag}/**`), and the index `## Team-Shared Tag Index` section (team-shared files in code repos under `_project-knowledge/`). All three contribute to the result set; results are categorized so Step 5 can present them grouped.

**Matching rule (extended 2.16.0):** for any source, a query token `t` matches a file `f` if either: 1. `t` equals a tag declared by `f` (existing behavior), OR 2. `t.lower()` (with hyphens stripped) appears as a substring of any phrase in `f`'s `semantic-hints:` frontmatter (also lowercased + hyphen-stripped).

The `## Semantic Hints Index` in `index.md` is the discovery surface for hint matches — Step 4a scans both `## Tag Index` / `## Other Tags` AND `## Semantic Hints Index` for query-token matches. AND/OR mode applies per-token: each token can satisfy independently via tag OR hint.

When a file matches via hint rather than tag, append `[hint: <phrase>]` to the Step 5 result render so the user can see why the file was surfaced.

Step 4a: Index-driven matches (cross-project)

Scan the `## Tag Index` and `## Other Tags` sections for entries matching the query tags.

**Exclude files whose path starts with `projects/`** — those are project-tier files, handled by Step 4b