setup

/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 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/.codex-plugin/plugin.json 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:

ARIA_PLUGIN_ROOT="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"
INSTALLED_VERSION=$(grep '"version"' "${ARIA_PLUGIN_ROOT}/.codex-plugin/plugin.json" | head -1 | sed 's/.*"version": *"\([^"]*\)".*/\1/')

Then read ~/.claude/aria-knowledge.local.md. The Codex port intentionally shares this config file with the Claude Code port when both are installed, so the knowledge folder, cadence settings, project tier, and shared-knowledge settings stay in one place. If a legacy ~/.codex/aria-knowledge.local.md exists and the shared config does not, offer to copy it to ~/.claude/aria-knowledge.local.md; otherwise leave it untouched and report that Codex now uses the shared config.

• 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:$' ~/.claude/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}' ~/.claude/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 ${ARIA_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. Your customizations live here safely.

See OVERVIEW.md "Plugin-Managed vs User-Owned Files" for details. This note appears only on first setup.

In existing mode: Scan what's present vs missing.

• For missing directories: create them silently.
• For missing files: copy from template and note what was added.
• For existing files: do NOT overwrite — collect for diffing in Step 4.
• Report: "Created N directories, added N files, found N existing files to check."

Project tier scaffolding (if projects_enabled: true in current or pending config) is deferred to Step 7c — it runs after the config is written so it uses the final values (including answers from Step 6 that aren't in the config file yet during Step 3).

Step 3b: Legacy ideas-backlog.md Detection

ARIA v2.11 moved the ideas backlog from a single intake/ideas-backlog.md file to per-file storage under intake/ideas/. Users upgrading from v2.10.x or earlier have an orphaned legacy file that v2.11 skills don't read. This step catches the migration on the first post-upgrade /setup run.

Check: does {knowledge_folder}/intake/ideas-backlog.md exist?

• If no: skip this step silently. Fresh installs and already-migrated users land here.
• If yes: count active entries by running:

``bash awk '/^---$/{sep++; next} sep>=1 && /^### /{c++} END{print c+0}' "{knowledge_folder}/intake/ideas-backlog.md" ``

• If count is 0: the legacy file has no active entries (cleared-history HTML comments only). Prompt: "Empty pre-2.11 ideas-backlog.md found. Delete it? (y/n)" — on yes, rm the file; on no, leave it.
• If count > 0: report: *"Pre-2.11 ideas-backlog.md detected wit