aria-setup

/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 of the standard subdirectories: intake/, decisions/, etc.)

If the read succeeds: the folder is granted to this Cowork session. Proceed to Step 4 (folder structure validation).

If the read fails with an error like "outside this session's connected folders, so Read can't reach it": the folder isn't granted yet. Proceed to Step 3 (grant guidance).

If the read fails because the path doesn't exist on disk (different from the access-denied error): proceed to Step 4 in fresh mode — assume the user wants a new folder created at this path; continue with the scaffold flow.

Step 3: Guide claude_desktop_config.json edit (if folder unreachable)

The user's knowledge folder needs persistent grant via Cowork's desktop config. Provide step-by-step instructions:

"To make <KNOWLEDGE_FOLDER> reachable from every Cowork session, add it to your Cowork desktop config. Here's how:

1. Open or create the Cowork desktop config file. On macOS, this is typically at:

~/Library/Application Support/Claude/claude_desktop_config.json

2. Add your knowledge folder to the additional directories list. The exact key may be additionalDirectories, additional_directories, or similar — check your existing config or Cowork's docs for the correct field name. Example shape:

```json*

{*

"additionalDirectories": [*

"<KNOWLEDGE_FOLDER>"*

]*

}*

```*

3. Save the file and restart Cowork (or reload the plugin) so the grant takes effect.

4. Re-run /aria-setup to continue scaffolding.

Alternative for one-off testing without persistent grant: run /add-dir <KNOWLEDGE_FOLDER> in this Cowork conversation to grant access for the current session only. Persistent grant via desktop config is recommended for normal use — it works across all your Cowork projects without re-granting."

Stop here until the user re-runs /aria-setup after the grant.

Step 4: Folder structure scaffold

The folder is reachable. Read the expected structure from ${CLAUDE_PLUGIN_ROOT}/template/.

Expected directories (create if missing): intake/, intake/clippings/, intake/notes/, intake/attachments/, decisions/, approaches/, guides/, references/, archive/, rules/, logs/

Expected files (copy from ${CLAUDE_PLUGIN_ROOT}/template/<file> if missing): README.md, OVERVIEW.md, LOCAL.md, aliases.md (user-owned, added v0.3.0 — see "User-owned templates" below), intake/insights-backlog.md, intake/decisions-backlog.md, intake/extraction-backlog.md, intake/rules-backlog.md, rules/working-rules.md, rules/change-decision-framework.md, `rule