onboard

name	onboard
description	First-run setup for buttondown-mgmt. Registers one or more Buttondown newsletters (each with its own API key reference and user directory), provisions the shared template store, and clones the official Buttondown docs into the local cache.

Onboard

Run on first use, or when the user wants to reconfigure the plugin. Supports multiple newsletters — each newsletter has its own API key, user directory, and default-status flag.

Data locations

DATA_ROOT="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/buttondown-mgmt"
mkdir -p "$DATA_ROOT/cache/docs" "$DATA_ROOT/templates" "$DATA_ROOT/data" "$DATA_ROOT/state"

Config goes in $DATA_ROOT/config.json. Never write config to ~/.claude/.

Steps

1. Register first newsletter. Ask:
   • Slug (kebab-case identifier, e.g. sitrepisr)
   • Display name (e.g. "Israel SITREP")
   • API key reference — prefer 1Password (op://...) over raw key
   • User directory — path for drafts/sent/exports for this newsletter (suggest ~/Documents/Buttondown/<slug>/); create if missing
   • Mark this one as default (first newsletter is default unless user says otherwise)
2. Offer to register more. Loop until the user says no. Subsequent newsletters use the same prompts; default flag can only be set on one.
3. Docs cache. Invoke refresh-docs to clone https://github.com/buttondown/docs into $DATA_ROOT/cache/docs/.
4. Template store. Note that $DATA_ROOT/templates/ is the shared template store across newsletters; user can scope a template to a specific newsletter via the add-template skill.
5. CLI check (optional). command -v buttondown — if missing, point at upstream README, don't auto-install.
6. Confirm. Print resolved paths, list of registered newsletters with [default] marker, and the templates directory.

config.json shape

{
  "newsletters": {
    "sitrepisr": {
      "name": "Israel SITREP",
      "api_key_ref": "op://Personal/Buttondown sitrepisr/api_key",
      "user_dir": "/home/<user>/Documents/Buttondown/sitrepisr",
      "default": true
    },
    "tech-notes": {
      "name": "Tech Notes",
      "api_key_ref": "op://Personal/Buttondown tech-notes/api_key",
      "user_dir": "/home/<user>/Documents/Buttondown/tech-notes",
      "default": false
    }
  },
  "templates_dir": "<DATA_ROOT>/templates",
  "docs_cache": "<DATA_ROOT>/cache/docs",
   

Reconfiguration

If config.json already exists, ask whether the user wants to (a) add another newsletter (delegate to add-newsletter), (b) edit an existing entry, or (c) start over (back up old config to config.json.bak-<timestamp> first).