/aria-setup

name: aria-setup
description: Configure aria-cowork on first run or after updates. Verifies your knowledge folder is reachable from this Cowork session, guides you through adding it to claude_desktop_config.json for persistent multi-session access if needed, scaffolds the folder structure, and writes the canonical aria-config.md. Safe to re-run anytime — only touches what.
compatibility: Requires Cowork desktop app. Default knowledge folder is `~/Projects/knowledge/`; users with non-default locations can override via inline prompt at first /aria-setup run. Works in any project workspace once the knowledge folder is granted via claude_desktop_config.json.

/aria-setup — aria-cowork Configuration

Verify the knowledge folder is reachable, guide setup if it isn't, and scaffold structure. Safe to re-run anytime.

Step 0: Read installed plugin version

**Read the installed plugin version first.** Parse `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` and extract the `version` field. Hold it as `INSTALLED_VERSION` for use in Step 5 (config write) and Step 6 (summary). Use grep + sed to stay consistent with the no-jq invariant aria-knowledge's hook scripts follow:

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

All references to the version below use `{INSTALLED_VERSION}` as a substitution placeholder — the agent expands it from the captured value at runtime, so the skill body doesn't need editing per release.

Step 1: Determine the knowledge folder path

aria-cowork v{INSTALLED_VERSION} uses a **default-path convention**: the knowledge folder is `~/Projects/knowledge/` (expand `~` to the user's home directory at runtime, producing an absolute path like `/Users/<user>/Projects/knowledge`).

Hold the default as `DEFAULT_KNOWLEDGE_FOLDER` (e.g., `~/Projects/knowledge` — expand `~` to your home directory's absolute path).

**Override mechanism for non-default locations:**

Try reading `<DEFAULT_KNOWLEDGE_FOLDER>/aria-config.md` first.

• **If it exists**: read the `knowledge_folder:` field from its frontmatter. If that field's value differs from `DEFAULT_KNOWLEDGE_FOLDER`, use the override (the user has previously configured a non-default location). Hold as `KNOWLEDGE_FOLDER`.
• **If it doesn't exist** AND the default folder also doesn't exist on disk: this is a fresh install. Ask the user inline:

> *"aria-cowork doesn't have a knowledge folder configured yet. The default location is `~/Projects/knowledge/`. Press enter to use the default, or type an alternate absolute path:"*

If user accepts default or provides a path, use that as `KNOWLEDGE_FOLDER`. The `/aria-setup` flow will create it and scaffold structure.

• **If the default exists but `aria-config.md` is missing**: existing folder, no aria-cowork config yet. Use `DEFAULT_KNOWLEDGE_FOLDER` and write a fresh aria-config.md in Step 5.

Hold the resolved value as `KNOWLEDGE_FOLDER`.

Step 1b: Access probe (added v0.3.0 — cowork-only per B1)

Cowork's persistent-grant model can fail in subtler ways than a simple read can detect — a read-only grant, a revoked write permission, or filesystem errors that only surface on write. Step 1b runs a full read+write+delete round-trip to verify true folder access before any scaffolding proceeds.

**Probe sequence:**

1. **Read existence check** — attempt to Read `<KNOWLEDGE_FOLDER>/aria-config.md`. File-not-found is recoverable (fresh install); access-denied is a probe failure. 2. **Write probe** — Write a temp file at `<KNOWLEDGE_FOLDER>/.aria-probe-{timestamp}` containing the literal line `aria-cowork access probe — safe to delete`. Use the current Unix timestamp as `{timestamp}` for filename uniqueness across concurrent probes. 3. **Round-trip read** — Read the just-written probe file back to confirm the write persisted and is readable. 4. **Cleanup** — delete the probe file. If delete fails, surface a warning (probe content was harmless, but the user may want to remove `.aria-probe-*` files manually). 5. **Report PASS** if all four steps succeeded. Continue to Step 2.

**Failure handling:**

| Failure mode | Diagnostic surfaced | |---|---| | Read access denied | *"`<KNOWLEDGE_FOLDER>` is not granted to this Cowork session. The folder may exist but Cowork can't reach it — likely a missing or revoked persistent grant. Continue to Step 3 for grant-recovery guidance."* | | Read succeeds but write fails | *"`<KNOWLEDGE_FOLDER>` is read-only from this Cowork session. aria-cowork needs write access to scaffold structure and persist config. Likely a read-only mount or restricted grant scope — check the persistent grant in `claude_desktop_config.json` and ensure it covers write."* | | Write succeeds but round-trip read fails | *"Cowork wrote to `<KNOWLEDGE_FOLDER>` but couldn't read the file back. Likely a filesystem sync issue or transient FS error. Re-run `/aria-setup` to retry; if the problem persists, check disk health."* | | Delete fails after probe success | (Warning, not halt) *"Probe completed but couldn't remove the temporary probe file. Safe to delete manually: `<KNOWLEDGE_FOLDER>/.aria-probe-*`."* |

**On any halt-class failure (rows 1-3), stop and surface the diagnostic.** Do not proceed to Step 2 or beyond — Step 2's simpler read check would fail too, and Step 3's grant guidance is the actionable next step for read-denied failures.

This probe is unique to aria-cowork — aria-knowledge runs in Code with default filesystem access and doesn't need this check. The probe productizes the field-validation lessons from the 2026-04-30 probe arc (probes 2, 3, 11) as a per-setup invariant.

Step 2: Verify reachability

Try reading a file at the expected path. Use either:

• `<KNOWLEDGE_FOLDER>/aria-config.md` if it already exists (returning user)
• `<KNOWLEDGE_FOLDER>/README.md` (created by template seed during fresh install)
• A directory listing of `<KNOWLEDGE_FOLDER>` (any