arscontexta 0.6.0

package/skills/health/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "knowledge-health",
+  "description": "Run vault maintenance checks -- orphans, schema compliance, description quality, link health, stale notes, MOC coherence. Returns an actionable report with specific fixes.",
+  "version": "0.4.0",
+  "author": "arscontexta",
+  "tags": ["knowledge-management", "meta-cognitive", "maintenance"],
+  "entry": "SKILL.md",
+  "platform_hints": {
+    "claude-code": {
+      "context": "fork",
+      "model": "opus"
+    },
+    "openclaw": {
+      "type": "external"
+    }
+  }
+}

package/skills/help/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: help
+description: Contextual guidance and command discovery. Three modes — narrative (first-time), contextual (mid-task), compact (quick reference). Shows available commands, active skills, and intelligent suggestions based on vault state. Triggers on "/help", "what can I do", "show commands", "how does this work".
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+---
+
+## 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)
+
+```bash
+# 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.

package/skills/help/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "knowledge-help",
+  "description": "Contextual guidance and command discovery. Shows available commands, active skills, and intelligent suggestions based on vault state.",
+  "version": "0.4.0",
+  "author": "arscontexta",
+  "tags": ["knowledge-management", "onboarding", "setup"],
+  "entry": "SKILL.md",
+  "platform_hints": {
+    "claude-code": {
+      "context": "inline",
+      "model": "sonnet"
+    },
+    "openclaw": {
+      "type": "external"
+    }
+  }
+}