help

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target contains --compact: force compact mode regardless of vault state
• If target contains a skill name (e.g., "help reduce" or "help reflect"): show detailed help for that specific skill
• If target is empty: determine mode from vault state

Execute these steps:

1. Gather vault state (Step 1)
2. Resolve domain vocabulary (Step 2)
3. Determine mode (Step 3)
4. Discover commands dynamically (Step 4)
5. Render the appropriate mode (Step 5)

START NOW. Reference below defines each step.

---

Step 1: Gather Vault State

Determine the notes folder by checking which domain-named directory exists (notes/, reflections/, concepts/, ideas/, decisions/, memories/, or any custom name from derivation-manifest.md). Then gather counts:

• Note count: .md files in the notes folder, excluding MOCs (files with type: moc in frontmatter)
• Inbox count: .md files in the inbox folder (inbox/, journal/, encounters/, etc.)
• Observation count: .md files in ops/observations/ or ops/methodology/
• Tension count: .md files in ops/tensions/
• Connection density: count wiki links ([[) across notes folder; sparse if fewer than 2x note count
• Queue state: pending tasks in ops/queue/queue.yaml or ops/queue/queue.json
• Health warnings: check latest report in ops/health/ if it exists
• Tutorial state: check ops/tutorial-state.yaml for incomplete tutorial
• Session count: estimate from ops/sessions/ file count (indicates usage maturity)

# Quick state gathering
note_count=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
inbox_count=$(ls -1 {vocabulary.inbox}/*.md 2>/dev/null | wc -l | tr -d ' ')
obs_count=$(ls -1 ops/observations/*.md ops/methodology/*.md 2>/dev/null | wc -l | tr -d ' ')
tension_count=$(ls -1 ops/tensions/*.md 2>/dev/null | wc -l | tr -d ' ')

Step 2: Resolve Domain Vocabulary

Read ops/derivation-manifest.md (or fall back to ops/derivation.md Vocabulary Mapping section). Extract domain-native names for: reduce, reflect, reweave, verify, rethink, note, MOC, inbox. If neither file exists, use universal names.

For display, show domain name with universal in parentheses when they differ:

  /{domain:reduce} (reduce)   Extract patterns from journal entries

If domain name equals universal name, show just the name:

  /reduce   Extract insights from source material

Step 3: Determine Mode

Condition	Mode
--compact in arguments	Compact
Specific skill name in arguments	Skill detail
Note count < 5	Narrative
Note count >= 5	Contextual

Step 4: Discover Commands

Scan ${CLAUDE_PLUGIN_ROOT}/skills/ dynamically:

• Subdirectories containing SKILL.md (e.g., reduce/SKILL.md)

Extract name: and description: from each frontmatter. Do NOT hardcode the command list.

Command categories:

Category	Commands	When to Show
Core	/ask, /learn, /next, /help	Always
Processing	/reduce, /reflect, /reweave, /verify	Always (all skills from day one)
Maintenance	/health, /rethink, /remember	Always
Evolution	/architect, /reseed, /add-domain, /upgrade	Always
Meta	/tutorial, /graph, /stats	Always

Step 5: Render

NARRATIVE MODE (note count < 5)

This is the first impression. The user is new or nearly new. Explain what the system IS before listing what it DOES.

What narrative mode communicates:

1. What Ars Contexta is (one sentence)
2. What THEIR system was built to do (read from ops/derivation.md if available)
3. What they can do RIGHT NOW (concrete actions, not abstract possibilities)
4. How the system grows with them

--=={ ars contexta : help }==--

Your knowledge system is ready. It turns thoughts
into a connected graph where every note compounds
the value of every other note.

[If ops/derivation.md exists:]
Your system: [domain description from derivation]

Getting started:

  Tell me a thought, observation, or question.
  I will turn it into a note and show you what
  the system does with it.

  Or try one of these:

  /ask [question]    Ask about [domain] -- I will
                     answer from your graph
  /learn [topic]     Research [topic] and grow
                     your graph with findings
  /tutorial          Walk through the system
                     step by step (5 minutes)

As your graph grows, you will use:
  /reduce [source]   Extract insights from articles,
                     notes, or any raw material
  /reflect           Find connections between notes
  /health            Check your system's health

Your system also learns from experience:
  /remember             Capture when something goes wrong
                        (your system remembers corrections)
  /ask [question]       Ask about [domain] -- answers draw
                        from 249 methodology notes AND your
                        system's own methodology notes

Type /help anytime for guidance.

Manual reference (if manual/ exists): If the vault contains a manual/ directory, add to the narrative output:

  For a deeper guide, read manual/getting-started.md
  or explore the full manual in manual/manual.md.

Key principles for narrative mode:

• Conversational, not list-like
• Show the easiest entry point first ("tell me a thought")
• Group commands by when the user would need them, not alphabetically
• Reference the user's actual domain when possible
• If tutorial is incomplete, mention: "You have an unfinished tutorial (step N of 5). Resume with /tutorial"

CONTEXTUAL MODE (note count >= 5)

The user has been working. Show them what is happening NOW and what would be most valuable NEXT.

What contextual mode communicates:

1. Current system state (brief metrics)
2. What needs attention right now (state-aware)
3. Suggested next action (the single most valuable thing)
4. Commands they might not know yet
5. Full command reference

--=={ ars contexta : help }==--

Your system: [domain] knowledge graph
  [N] notes, [M] connections, [P] pending tasks

Right now:
  [State-aware observations — pick up to 3 most relevant:]
  Your inbox has [N] items (oldest: [age])
  [N] pending observations -- approaching /rethink threshold
  Pipeline: [N] tasks at [phase] phase
  [N] notes have sparse connections (< 2 links)

Suggested:
  [Single most valuable next action with rationale]

[If user hasn't tried certain commands:]
Commands you might not know:
  /remember    Capture when something goes wrong
               (teaches your system from friction)
  /graph       Explore your knowledge graph visually
  /stats       See vault metrics in shareable format

All commands:
  /ask [question]        Query your knowledge system
  /learn [topic]         Research and grow your graph
  /next                  Next recommended action
  /{reduce} [source]     Extract insights from material
  /{reflect}             Find connections between notes
  /{reweave}             Update older notes
  /verify [note]         Combined quality verification
  /health                Run vault diagnostics
  /{rethink}             Challenge assumptions
  /remember              Capture methodology learning
  /architect             Research-backed evolution advice
  /reseed                Principled restructuring
  /add-domain            Extend with a new domain
  /upgrade               Check for skill improvements
  /tutorial              Interactive walkthrough
  /graph                 Graph exploration
  /stats                 Vault metrics

State-aware suggestion logic:

Pick the FIRST matching condition:

Condition	Suggestion
Inbox has items	Process your inbox: /{reduce} [oldest-inbox-item-filename]
Pipeline has pending tasks	Resume processing: /next
10+ observations or 5+ tensions	Review accumulated evidence: /{rethink}
Health warnings exist	Check health: /health
Notes exist, sparse connections	Build connections: /{reflect}
User hasn't tried /learn	Grow your graph: /learn [topic related to their domain]
Methodology folder has friction notes	Your system is learning from friction -- review with /{rethink}
Methodology folder has notes beyond derivation-rationale	Your system has [N] operational learnings -- query them with /ask or browse ops/methodology/
Sessions accumulating without mining	Mine session learnings: /remember
Healthy vault, no pressure	What is next: /next

Reference a specific file when possible (e.g., the actual oldest inbox filename, the actual pending task description).

Manual page suggestion (if manual/ exists): Based on the first matching state-aware condition, suggest the relevant manual page:

Condition	Manual Page
Inbox has items	[[workflows]] (processing pipeline)
Pipeline has pending tasks	[[workflows]] (batch processing)
Observations/tensions accumulated	[[meta-skills]] (/rethink guide)
Health warnings exist	[[troubleshooting]]
Sparse connections	[[workflows]] (connection finding)
General orientation needed	[[getting-started]]

Add: For details, see manual/{page}.md

"Commands you might not know" logic:

Track which commands the user has likely used by checking for their artifacts:

• /learn used if ops/sessions/ has learn-related transcripts or inbox has research files
• /remember used if ops/methodology/ or ops/observations/ has files
• /graph used if... (no artifact, always suggest if note count > 20)
• /stats used if... (no artifact, always suggest if note count > 10)

Show up to 3 commands the user probably has not tried. Skip commands they clearly have used.

COMPACT MODE (--compact flag)

Quick reference. No state analysis. No suggestions. Just the commands.

--=={ ars contexta : help --compact }==--

  /ask [question]        Query knowledge system
  /learn [topic]         Research and grow graph
  /next                  Next recommended action
  /{reduce} [source]     Extract insights
  /{reflect}             Find connections
  /{reweave}             Update older notes
  /verify [note]         Quality verification
  /health                Vault diagnostics
  /{rethink}             Challenge assumptions
  /remember              Capture methodology learning
  /architect             Evolution advice
  /reseed                Restructure system
  /add-domain            Add new domain
  /upgrade               Check for improvements
  /tutorial              Interactive walkthrough
  /graph                 Graph exploration
  /stats                 Vault metrics
  /help                  This guide

SKILL DETAIL MODE (help [skill-name])

When the user asks for help with a specific skill (e.g., /help reduce or /help reflect):

1. Find the skill's SKILL.md file
2. Read its frontmatter (name, description) and first section
3. Display a focused guide:

--=={ ars contexta : help /{skill-name} }==--

{Description from frontmatter}

Usage:
  /{skill-name} [arguments]

Examples:
  /{skill-name} inbox/article.md
  /{skill-name} --since 7d

What it does:
  {2-3 sentence summary extracted from the skill's
   philosophy or first methodology section}

Related:
  /{related-skill}    {one-line description}

Special case for /help ask: Expand the "What it does" section to mention both knowledge layers:

What it does:
  Queries the bundled methodology knowledge base (249
  research claims) AND your local methodology notes
  in ops/methodology/. Answers are grounded in
  specific claims and applied to your system's
  configuration.

Extract the pipeline position (what comes before and after this skill) to show workflow context.

Manual cross-reference: If manual/skills.md exists, also check it for additional context about the requested skill. The manual may contain domain-specific examples and workflow context that the SKILL.md frontmatter does not include.

---

Rendering Rules

• Max width: 76 characters
• No ANSI color codes
• No emoji
• Monospaced alignment assumed
• Display short command forms (/reduce), not plugin-qualified forms (/arscontexta:reduce)
• Domain-native names in curly braces (e.g., /{reduce}) are resolved from derivation-manifest.md
• When domain name equals universal name, drop the braces

Edge Cases

No ops/derivation-manifest.md: Use universal vocabulary for all command names.

Pre-init invocation: If no vault structure exists at all (no notes folder, no ops/), show a minimal message:

Ars Contexta is not initialized in this directory.
Run /setup to create your knowledge system.

Multiple domains: If ops/derivation-manifest.md lists multiple domains, show commands grouped by domain in contextual mode.