/setup

description: "Configure aria-knowledge plugin. Creates or validates a knowledge folder, checks dependencies, sets audit cadences, and writes config. Run on first install or after plugin updates. Trigger: '/setup', 'setup aria-knowledge', 'configure knowledge'."

/setup — Knowledge Tools Configuration

Walk the user through configuring their knowledge folder and plugin settings. Safe to re-run at any time — only touches what needs updating.

Step 1: Check for Existing Config

**Read the installed plugin version first.** Parse `${CLAUDE_PLUGIN_ROOT}/version.txt` and extract the `version` field. Hold it as `INSTALLED_VERSION` for use in Step 7 (config write), Step 8 (summary), and the announcement below. Use grep + sed to stay consistent with the no-jq invariant the hook scripts follow:

INSTALLED_VERSION=$(cat "${CLAUDE_PLUGIN_ROOT}/version.txt")

Then read `~/.gemini/antigravity/aria-knowledge.local.md`.

• **If it exists:** show current settings and say *"aria-knowledge v{INSTALLED_VERSION} is already configured. I'll check for updates."* If the existing config has `last_setup_version: X` and X differs from `INSTALLED_VERSION`, also note: *"Plugin upgraded from v{X} → v{INSTALLED_VERSION} since last setup. Diff prompts and any new config keys will surface in the steps below."* Then proceed to Step 2 in **update mode** — scan for missing structure, re-diff templated files, check dependencies.
• **If it doesn't exist:** say *"Let's set up aria-knowledge v{INSTALLED_VERSION}. This will configure your knowledge folder and preferences."* Proceed to Step 2 in **fresh mode**.

**Detect skill-only fields** (update mode only). After parsing the standard hook-parsed keys, also scan for the `projects_groups` multi-line YAML block — a skill-only field consumed by `/distill` and `/stitch` (see `CONFIG.md` for schema). It's **not** in the advanced-options bundle because it's not bash-parsed; surface its presence here so users get awareness without /setup trying to flatten it.

GROUPS_PRESENT=$(grep -c '^projects_groups:$' ~/.gemini/antigravity/aria-knowledge.local.md || true)
GROUPS_COUNT=$(awk '/^projects_groups:$/{in_block=1; next} in_block && /^---$/{exit} in_block && /^[^[:space:]]/{exit} in_block && /^  [^[:space:]].*:$/{c++} END{print c+0}' ~/.gemini/antigravity/aria-knowledge.local.md)

If `GROUPS_PRESENT > 0`, add to the announcement: *"Detected `projects_groups` skill-only field with {GROUPS_COUNT} group(s) configured. Preserved as-is (consumed by `/distill` and `/stitch`; see `CONFIG.md` for the schema)."* If `GROUPS_PRESENT == 0`, say nothing — the field is opt-in and most users without multi-repo projects won't have it.

Step 2: Knowledge Folder Location

Ask the user: > "Where would you like your knowledge folder? You can: > (a) Provide a path to an existing folder > (b) Create a new one — I'll ask where to put it"

If **(a) existing path:**

• Verify the path exists and is a directory
• Proceed to Step 3 in **existing mode**

If **(b) create new:**

• Ask for the desired location (parent directory + folder name)
• Create the directory
• Proceed to Step 3 in **create mode**

Step 3: Folder Structure Validation

Read the expected structure from `${CLAUDE_PLUGIN_ROOT}/template/`.

**Expected directories:** `intake/`, `intake/notes/`, `intake/attachments/`, `intake/clippings/`, `intake/pre-compact-captures/`, `intake/subagent-captures/`, `intake/ideas/`, `logs/`, `rules/`, `approaches/`, `decisions/`, `guides/`, `references/`, `archive/`

**Expected files:** `README.md`, `OVERVIEW.md`, `LOCAL.md`, `aliases.md`, `intake/insights-backlog.md`, `intake/decisions-backlog.md`, `intake/extraction-backlog.md`, `intake/rules-backlog.md`, `intake/ideas/README.md`, `logs/knowledge-audit-log.md`, `logs/config-audit-log.md`, `rules/working-rules.md`, `rules/user-rules.md`, `rules/user-examples.md`, `rules/change-decision-framework.md`, `rules/enforcement-mechanisms.md`, `guides/README.md`, `approaches/README.md`, `decisions/README.md`, `references/README.md`, `archive/README.md`

**User-owned files (created once from template, never overwritten or diffed):** `LOCAL.md` (project-specific guide), `aliases.md` (tag aliases — added 2.16.0), `rules/user-rules.md` (your custom rules — ARIA never touches this file), `rules/user-examples.md` (your per-rule examples — `/rules N` reads this; ARIA never touches this file), `guides/README.md`, `approaches/README.md`, `decisions/README.md`, `references/README.md`, `archive/README.md` (directory stubs users may customize).

**In create mode:** Create all directories and copy all template files. After creation, display a **one-time educational note** about the file-class model (this note is only shown on fresh installs — in update/existing mode, skip it):

> **First-setup note: Plugin-Managed vs User-Owned Files** > > Your knowledge folder now contains two classes of template files: > > - **Plugin-managed** — `README.md`, `OVERVIEW.md`, `rules/working-rules.md`, `rules/change-decision-framework.md`, `rules/enforcement-mechanisms.md`, `rules/retrospect-patterns.md` (and `projects/README.md` when the project tier is enabled). These are diffed on every `/setup` run. Customize them freely — your edits will appear as diff prompts when plugin updates ship. That's how you receive improvements without silent overwrites. Each managed file also carries a `<!-- plugin-managed: -->` comment header so you can spot them at edit time. > - **User-owned** — `LOCAL.md`, `aliases.md`, `rules/user-rules.md`, `rules/user-examples.md` (your per-rule examples, since v2.14.2), intake backlogs (`insights-backlog.md`, `decisions-backlog.md`, `extraction-backlog.md`, `rules-backlog.md`) and the `intake/ideas/` directory (one file per idea since v2.11), audit logs under `logs/`, directory README stubs (`guides/`, `approaches/`, `decisions/`, `references/`, `archive/`), and per-project READMEs under `projects/{tag}/`. ARIA never diffs or overwrites these. Y