setup

name	setup
disable-model-invocation	true
description	Single entry point for Myna onboarding — detects install state, runs first-time scaffolding if needed, opens the Config UI or runs doc import, and adds shell aliases. Use for first-time setup or returning configuration.
user-invocable	true
argument-hint	setup | review config | add a project | add people

myna-setup

Single entry point for all Myna configuration — new installs and returning users alike. Detects whether Myna is already installed, runs the install script if not, then opens the Config UI (or doc import as an alternative). No guided interview.

${CLAUDE_SKILL_DIR} is the directory containing this SKILL.md file, resolved by the plugin runtime to the skill's install location.

---

Step 0: Detect Install State

Read ~/.myna/config.yaml.

• If it exists: parse vault_path from it. Skip to Step 3 (Config UI).
• If it does not exist: say "Welcome! Let's get Myna set up." and continue to Step 1.

---

Step 1: Gather Vault Details (first-time only)

Ask the user one question:

1. Full path to your Myna vault — a folder on your machine where Myna stores everything. Using Obsidian? Point it to your Obsidian vault. (e.g. /Users/you/Documents/MyVault)

Then continue to Step 2.

---

Step 2: Run Install Script (first-time only)

Run the install script in the foreground:

bash "${CLAUDE_SKILL_DIR}/../../install/claude.sh" "<vault_path>" "myna"

Show all progress output as it runs. If the script exits non-zero, show the error output and stop — do not proceed to Step 3.

---

Step 3: Config UI

Check if python3 is available:

python3 --version

If python3 is not available:

Check if brew is available:

brew --version

• If brew is available: Ask: "The Config UI needs Python 3. Want me to install it? (brew install python3)"

  • If yes: run brew install python3, then continue to the python3 available path below.
  • If no: show config file paths (see below) and stop.

• If brew is not available: Say: "The Config UI needs Python 3. Install it from https://python.org and re-run /myna:setup." Then ask: "Or would you rather skip that for now and edit the config files directly?" If yes: show config file paths (see below). Stop either way.

Config file paths (shown only when user skips Python 3 install):

• {vault_path}/myna/_system/config/workspace.yaml — your identity (name, job title, timezone). Start here.
• {vault_path}/myna/_system/config/projects.yaml — the projects you're working on, with names, aliases, and which email folders or Slack channels map to each.
• {vault_path}/myna/_system/config/people.yaml — the people you work with: direct reports, manager, key collaborators, and their roles.
• {vault_path}/myna/_system/config/communication-style.yaml — your email sign-off. Myna handles tone automatically based on audience tier.
• {vault_path}/myna/_system/config/tags.yaml — custom keyword tags beyond what Myna auto-derives from projects and people. Safe to leave blank.

For annotated examples of each file's format, see the "Sample configuration" section in myna/guide.md.

If python3 is available:

1. Run in background: python3 "${CLAUDE_SKILL_DIR}/../../ui/server.py"
2. Capture PID and URL from stdout — lines starting with PID: and URL:. If PID capture fails, note it and proceed — the user can kill the server manually with pkill -f server.py.
3. Tell the user: "Config UI is open at {url}. Fill in what you can, then type 'done' here when you're finished."
4. Wait for the user to type 'done' (or similar confirmation) before continuing.
5. Kill the server: send SIGTERM to the captured PID. If PID capture failed, run pkill -f server.py as fallback.
6. Re-read all five user config files fresh from disk — {vault_path}/myna/_system/config/workspace.yaml, projects.yaml, people.yaml, communication-style.yaml, tags.yaml — and update the session context with the values just read. (meetings.yaml is machine-managed — skip it.) Show a complete human-readable summary covering every section of all five files: what is configured and what is still blank. This is the active config for the rest of the session.
7. Ask: "Do you have any existing docs — project notes, a team roster, meeting notes — you'd like me to read to fill in what's missing?" If yes, proceed with the doc import flow below.

---

Doc Import (optional follow-up)

Always present three explicit input options upfront before asking anything:

1. Share docs — paste text, give file paths, or share links. This skill extracts projects (name, status, timeline, key people, description) and people (name, role, relationship, team). If a link can't be accessed, ask the user to paste content instead.
2. List them — type a batch description of projects and/or people in any format. This skill structures it and confirms.
3. Skip for now — come back later via /myna:setup.

Reading files by type:

• PDF: Use Claude Code's Read tool directly — it handles PDFs natively. Do not write a script.
• docx: Check pandoc --version first. If available, run pandoc -t plain <file> to extract text. If pandoc is not found, check if python-docx is available by running python3 -c "import docx". If it is, extract text with: python3 -c "import docx, sys; d=docx.Document(sys.argv[1]); print('\n'.join(p.text for p in d.paragraphs))" <file>. If neither pandoc nor python-docx is available, tell the user: "I can't read .docx files directly. Please install either pandoc (brew install pandoc or your OS package manager) or python-docx (pip install python-docx), then re-run setup. Alternatively, paste the document contents directly into the chat." Do not write custom parsing scripts.

When extracting from docs or user input, populate both projects.yaml and people.yaml. Cross-reference: people mentioned in projects get added to people config; projects mentioned for people get linked.

Show all extracted data as a numbered human-readable list — never as YAML. Then present these options:

1. Write to config — save as-is and continue.
2. Inline corrections — reference by number in chat (e.g., "3: remove", "5: she's tech lead not senior"). Multiple corrections in one message are fine. Best for small batches.
3. Export to file — write extracted data to a human-readable file (not YAML) in the vault, let the user edit it in their editor, then read it back. Best for large batches.

Write YAML only when the user selects option 1 (or after corrections are applied via option 2 or 3 and the user selects option 1). When the user provides timeline information (even rough like "Q3" or "end of May"), include it in the project description field.

relationship_tier on import: Do not default relationship_tier to "direct" or any other value. Leave it blank (omit the field) unless the source doc explicitly states the relationship. After writing to people.yaml, show: "N people saved without a relationship tier." Then offer:

1. Set tiers now — present the people with blank tiers as a numbered list and let the user assign each.
2. Defer to later — append a checklist entry to _system/setup-pending.md for each person who needs a relationship tier set: - [ ] Set relationship tier for {name} — imported without tier.

Schema references: _system/config/projects.yaml, _system/config/people.yaml. For annotated field documentation, see the "Sample configuration" section in myna/guide.md.

Person .md files: After relationship tiers are resolved, create a .md file for each imported person. Read the person template from {vault_path}/myna/_system/templates/person.md if it exists; otherwise use the canonical minimal person template from foundations §2.2. Write files to {vault_path}/myna/People/{slug}.md where {slug} is the person's name lowercased with spaces replaced by hyphens. Fill in fields from the imported data; leave any unknown field blank (no placeholder text, no "TBD"). Use #{relationship-tier} as the relationship tag (not #tier/{relationship-tier}). Use slug-only wikilinks: [[{slug}]] not [[1-1s/{slug}]]. Do not overwrite an existing person file — if a file already exists for a person, skip it and notify the user which files were skipped and why.

Post-import timeline offer: After config is written and relationship tiers are resolved, if any of the imported documents were project update documents (status updates, progress reports, sprint summaries, or similar), ask: "Want me to create project timeline files from the update documents you imported? I'll add dated entries to each project's timeline." Wait for the user to say yes before doing anything — skip this step if they decline or don't respond to it.

---

Step 4: Shell Aliases (always — first-time and returning)

Ask once:

Want me to add the Myna shell aliases to your shell config? This lets you launch Myna with pre-approved tool permissions. (yes/no)

If yes, show the user exactly what will be added:

alias myna='claude --agent myna:agent --allowedTools "Read,Write,Edit,Glob,Grep,Bash(cd *),Bash(ls *),Bash(cat *),Bash(mv *),Bash(date *),Bash(TZ=* date *)"'
alias myna-ro='claude --agent myna:agent --allowedTools "Read,Glob,Grep"'

Note: Bash(mv *) is required by sync for archiving journal notes. Bash(date *) and Bash(TZ=* date *) are required for timezone-aware date resolution. MCP tools (email, calendar, Slack) are available automatically via the user's registered MCP servers — they do not need to be listed in --allowedTools.

Detect the shell rc file: if $SHELL is zsh, use ~/.zshrc; otherwise use ~/.bashrc.

Check whether alias myna= already appears in the rc file. If it does, skip appending and tell the user: "Alias already present in {rc_file} — skipping."

If not already present, show the exact lines that will be appended and confirm once more: "This will write to {rc_file} (outside the vault). Proceed?" Then append both aliases after confirmation. Tell the user: "Added aliases to {rc_file}. Run source {rc_file} or open a new terminal to activate them."

If no, print both alias lines and tell the user to add them manually if they want them later.

---

Step 5: Wrap-Up

Onboarding checklist: Append any setup items not yet completed in this session (e.g., integrations not configured, projects/people not imported, communication style not set) to {vault_path}/myna/_system/setup-pending.md as a checklist. Create the file if it doesn't exist. Do not include items the user already completed. Then append exactly one task to today's daily note: - [ ] Complete Myna setup checklist [[setup-pending]]. Use the slug-only wikilink — [[setup-pending]] not [[_system/setup-pending]].

Tell the user: "Run myna (or claude --agent myna:agent) and type sync to start your day."

---

Config Writing Rules

• Read the existing config file before writing. Preserve any fields the user didn't change.
• For projects.yaml and people.yaml: append new entries — never overwrite existing ones.
• For people.yaml: omit relationship_tier unless the source explicitly states it. Never default to "direct".
• Write valid YAML matching the schemas shown in the "Sample configuration" section of myna/guide.md.
• meetings.yaml is machine-managed state written by Myna's skills — do not include it in user-facing config summaries or write it during setup unless the user explicitly asks.
• tags.yaml is an extension point for custom keyword tags — not part of the guided flow. Don't write it unless the user explicitly asks.
• Import write-back: write only what was in the review file. When writing config after an import review (option 3 in the doc import section), write only the entries and fields present in the review file. Do not add blocks, sections, or fields — such as triage, defaults, or schema examples — that were not explicitly included by the user.
• Filter blank values from all list fields before writing. Before writing any YAML config file, drop every item in every list field that is an empty string, null, or whitespace-only string. This applies to all list fields across all config files — do not enumerate fields by name. Only non-empty, non-null values with at least one non-whitespace character are written.