context

/context — On-Demand Knowledge Retrieval

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

Step 0: Resolve Config

Read ~/.claude/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. This prevents duplicate listings when a project-tier file is discoverable via both its YAML tag (in the index) and its path (via Glob in Step 4b). Since /index (Phase 4+) scans project-tier files and adds them to the Tag Index with path-derived tags, a project file tagged agentic-ui would otherwise appear in both Step 4a (via the agentic-ui tag match) and Step 4b (via the projects/{tag}/** Glob) — the exclusion puts project-tier files under Step 4b's authoritative categorization.

Union mode (OR): Collect non-projects/ files that appear under any of the query tags. Deduplicate — each file appears once even if it matches multiple tags.

Intersection mode (AND): Collect non-projects/ files that appear under ALL of the query tags. A file must be listed under every specified tag.

For each matching file, collect:

• File path (relative to knowledge folder)
• Description (from the index entry)
• All tags the file carries (scan all tag sections for this file path)
• Category: cross-project

Step 4b: Filesystem-driven matches (project tier)

Skip this sub-step entirely if projects_enabled: false or projects_list is empty.

For each query tag that matches a configured project tag (i.e., is a key in the parsed projects_list from Step 0):

1. Glob {knowledge_folder}/projects/{tag}/**/*.md to find all project-specific files.
2. Exclude projects/{tag}/README.md from the results (it's per-project navigation, not knowledge content).
3. For each file found:
4. Read the YAML frontmatter to extract tags: (if present) and the file's first H1 or summary line as description (if tags: is missing, treat the file as carrying just the project tag).
5. In intersection mode (AND): only include the file if its tag set contains ALL query tags (the project tag is implicit since the file lives under projects/{tag}/).
6. In union mode (OR): include all files found by the Glob (matching the project tag is sufficient).
7. Mark each result with category: project-specific and the originating project tag.

Empty folder handling (Decision #8): If the Glob returns no files for a configured project tag, record a "no project-specific files yet in projects/{tag}/" note. Don't treat this as an error — Step 5 will mention it informationally and continue with cro