onboard

name	onboard
description	Use on first run to initialize the plugin: create data directories, write default config, and optionally set up datasheet caching.

Onboard

First-run initialization of the plugin. Resolves the canonical data-storage path, creates directory tree (data/, cache/datasheets/, state/, output/), writes a default config.json with user preferences, and idempotently sets up the environment. Re-running this skill is safe and does not overwrite existing config unless explicitly requested.

Data storage root:

${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/hardware-id-annotation/

When to use

• First time using the plugin after installation
• Data directories have been deleted and need recreation
• User wants to reset preferences to defaults
• User moves to a new machine and wants to re-initialize

Inputs to gather

• Datasheet caching — prompt: "Cache downloaded datasheets locally? [y/n]" (Default: yes)
• Output directory — confirm plugin output directory location (Default: ${CLAUDE_USER_DATA}/.../output/)
• Optional: reset flag — --reset to overwrite config.json even if it exists

Procedure

1. Resolve data-storage path using the canonical resolver:

   DATA_ROOT="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/hardware-id-annotation"
   

2. Create directory tree (idempotent, no error if exists):

   mkdir -p "${DATA_ROOT}/data"
   mkdir -p "${DATA_ROOT}/cache/datasheets"
   mkdir -p "${DATA_ROOT}/state"
   mkdir -p "${DATA_ROOT}/output"
   

3. Check for existing config.json. If present and not --reset, skip to step 5. Otherwise, proceed.

4. Prompt user for preferences:

   === Hardware ID Annotation Plugin — First Run Setup ===
   
   1. Enable datasheet caching?
      (Downloads and stores manufacturer datasheets locally for faster lookup.)
      [y/n]: 
   
   2. Default output directory for annotated images?
      (Press ENTER for default: ${DATA_ROOT}/output)
      Path:
   
   3. Default label style for annotate-board?
      [minimal|detailed]: minimal
   
   4. Enable web lookups for datasheet search?
      (Requires internet; can be toggled per-skill later.)
      [y/n]: y
   

5. Write config.json:

   {
     "plugin_version": "1.0.0",
     "data_root": "${DATA_ROOT}",
     "initialized_at": "ISO8601 timestamp",
     "preferences": {
       "datasheet_caching_enabled": true,
       "default_output_dir": "${DATA_ROOT}/output",
       "default_label_style": "minimal",
       "default_label_mode": "number",
       "color_by_default": "type",
       "web_lookup_enabled": true
     },
     "skill_readiness": {
       "identify-components": "ready",
       "annotate-board": "ready (requires Pillow)",
       "cross-check-specs" 
        
        
        
        
     
   
   

6. Create a README.txt with quick-start instructions:

   Hardware ID Annotation Plugin — Quick Start
   
   Data stored in: ${DATA_ROOT}/
   
   Skills:
   - identify-components: Catalog components from a hardware photo
   - annotate-board: Draw bounding boxes and labels on the photo
   - cross-check-specs: Fetch manufacturer datasheets
   - generate-bom: Create BOM from component list
   - prep-photo: Improve photo quality before identification
   - install-deps: Install Python dependencies
   
   Next steps:
   1. Run 'prep-photo' if your hardware photo is low-quality
   2. Run 'identify-components' with your photo
   3. Run 'annotate-board' to visualize the components
   4. Run 'cross-check-specs' to verify part numbers
   5. Run 'generate-bom' for a sourcing list
   
   For details, see SKILL.md files in skills/ directory.
   

   Write to: ${DATA_ROOT}/README.txt

7. Print status report:

   ✓ Data root: ${DATA_ROOT}
   ✓ Directories created: data/, cache/datasheets/, state/, output/
   ✓ Config written: config.json
   ✓ Datasheet caching: enabled
   ✓ Web lookups: enabled
   
   Plugin is ready. Run 'prep-photo' or 'identify-components' to get started.
   

Output / side effects

• Directory tree created under canonical data-storage path
• config.json written with user preferences
• README.txt created for quick reference
• Console: confirmation that initialization succeeded
• All subsequent skills can now assume the data structure exists

Safety / constraints

• Idempotent. Running onboard multiple times is safe; existing directories are reused, and config.json is only overwritten with --reset.
• Permissions — data directories are created under ${CLAUDE_USER_DATA} with user-only access (mode 0700).
• No external state — onboard does not call web APIs or check for dependencies; use install-deps to set up Python packages.
• Data path stability — once initialized, all skills reference the same canonical root; users should not manually move or rename the storage directory.