arscontexta 0.6.0

package/skill-sources/seed/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: seed
+description: Add a source file to the processing queue. Checks for duplicates, creates archive folder, moves source from inbox, creates extract task, and updates queue. Triggers on "/seed", "/seed [file]", "queue this for processing".
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+user-invocable: true
+context: fork
+model: opus
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+argument-hint: "[file] — path to source file to seed for processing"
+---
+
+## EXECUTE NOW
+
+**Target: $ARGUMENTS**
+
+The target MUST be a file path. If no target provided, list {DOMAIN:inbox}/ contents and ask which to seed.
+
+### Step 0: Read Vocabulary
+
+Read `ops/derivation-manifest.md` (or fall back to `ops/derivation.md`) for domain vocabulary mapping. All output must use domain-native terms. If neither file exists, use universal terms.
+
+**START NOW.** Seed the source file into the processing queue.
+
+---
+
+## Step 1: Validate Source
+
+Confirm the target file exists. If it does not, check common locations:
+- `{DOMAIN:inbox}/{filename}`
+- Subdirectories of {DOMAIN:inbox}/
+
+If the file cannot be found, report error and stop:
+```
+ERROR: Source file not found: {path}
+Checked: {locations checked}
+```
+
+Read the file to understand:
+- **Content type**: what kind of material is this? (research article, documentation, transcript, etc.)
+- **Size**: line count (affects chunking decisions in /reduce)
+- **Format**: markdown, plain text, structured data
+
+## Step 2: Duplicate Detection
+
+Check if this source has already been processed. Two levels of detection:
+
+### 2a. Filename Match
+
+Search the queue file and archive folders for matching source names:
+
+```bash
+SOURCE_NAME=$(basename "$FILE" .md | tr ' ' '-' | tr '[:upper:]' '[:lower:]')
+
+# Check queue for existing entry
+# Search in ops/queue.yaml, ops/queue/queue.yaml, or ops/queue/queue.json
+grep -l "$SOURCE_NAME" ops/queue*.yaml ops/queue/*.yaml ops/queue/*.json 2>/dev/null
+
+# Check archive folders
+ls -d ops/queue/archive/*-${SOURCE_NAME}* 2>/dev/null
+```
+
+### 2b. Content Similarity (if semantic search available)
+
+If semantic search is available (qmd MCP tools or CLI), check for content overlap:
+
+```
+mcp__qmd__search query="claims from {source filename}" limit=5
+```
+
+Or via keyword search in the {DOMAIN:notes}/ directory:
+```bash
+grep -rl "{key terms from source title}" {DOMAIN:notes}/ 2>/dev/null | head -5
+```
+
+### 2c. Report Duplicates
+
+If either check finds a match:
+- Show what was found (filename match or content overlap)
+- Ask: "This source may have been processed before. Proceed anyway? (y/n)"
+- If the user declines, stop cleanly
+- If the user confirms (or no duplicate found), continue
+
+## Step 3: Create Archive Structure
+
+Create the archive folder. The date-prefixed folder name ensures uniqueness.
+
+```bash
+DATE=$(date -u +"%Y-%m-%d")
+SOURCE_BASENAME=$(basename "$FILE" .md | tr ' ' '-' | tr '[:upper:]' '[:lower:]')
+ARCHIVE_DIR="ops/queue/archive/${DATE}-${SOURCE_BASENAME}"
+mkdir -p "$ARCHIVE_DIR"
+```
+
+The archive folder serves two purposes:
+1. Permanent home for the source file (moved from {DOMAIN:inbox})
+2. Destination for task files after batch completion (/archive-batch moves them here)
+
+## Step 4: Move Source to Archive
+
+Move the source file from its current location to the archive folder. This is the **claiming step** — once moved, the source is owned by this processing batch.
+
+**{DOMAIN:inbox} sources get moved:**
+```bash
+if [[ "$FILE" == *"{DOMAIN:inbox}"* ]] || [[ "$FILE" == *"inbox"* ]]; then
+  mv "$FILE" "$ARCHIVE_DIR/"
+  FINAL_SOURCE="$ARCHIVE_DIR/$(basename "$FILE")"
+fi
+```
+
+**Sources outside {DOMAIN:inbox} stay in place:**
+```bash
+# Living docs (like configuration files) stay where they are
+# Archive folder is still created for task files
+FINAL_SOURCE="$FILE"
+```
+
+Use `$FINAL_SOURCE` in the task file — this is the path all downstream phases reference.
+
+**Why move immediately:** All references (task files, {DOMAIN:note_plural}' Source footers) use the final archived path from the start. No path updates needed later. If it is in {DOMAIN:inbox}, it is unclaimed. Claimed sources live in archive.
+
+## Step 5: Determine Claim Numbering
+
+Find the highest existing claim number across the queue and archive to ensure globally unique claim IDs.
+
+```bash
+# Check queue for highest claim number in file references
+QUEUE_MAX=$(grep -oE '[0-9]{3}\.md' ops/queue*.yaml ops/queue/*.yaml 2>/dev/null | \
+  grep -oE '[0-9]{3}' | sort -n | tail -1)
+QUEUE_MAX=${QUEUE_MAX:-0}
+
+# Check archive for highest claim number
+ARCHIVE_MAX=$(find ops/queue/archive -name "*-[0-9][0-9][0-9].md" 2>/dev/null | \
+  grep -v summary | sed 's/.*-\([0-9][0-9][0-9]\)\.md/\1/' | sort -n | tail -1)
+ARCHIVE_MAX=${ARCHIVE_MAX:-0}
+
+# Next claim starts after the highest
+NEXT_CLAIM_START=$((QUEUE_MAX > ARCHIVE_MAX ? QUEUE_MAX + 1 : ARCHIVE_MAX + 1))
+```
+
+Claim numbers are globally unique and never reused across batches. This ensures every claim file name (`{source}-{NNN}.md`) is unique vault-wide.
+
+## Step 6: Create Extract Task File
+
+Write the task file to `ops/queue/${SOURCE_BASENAME}.md`:
+
+```markdown
+---
+id: {SOURCE_BASENAME}
+type: extract
+source: {FINAL_SOURCE}
+original_path: {original file path before move}
+archive_folder: {ARCHIVE_DIR}
+created: {UTC timestamp}
+next_claim_start: {NEXT_CLAIM_START}
+---
+
+# Extract {DOMAIN:note_plural} from {source filename}
+
+## Source
+Original: {original file path}
+Archived: {FINAL_SOURCE}
+Size: {line count} lines
+Content type: {detected type}
+
+## Scope
+{scope guidance if provided via --scope, otherwise: "Full document"}
+
+## Acceptance Criteria
+- Extract claims, implementation ideas, tensions, and testable hypotheses
+- Duplicate check against {DOMAIN:notes}/ during extraction
+- Near-duplicates create enrichment tasks (do not skip)
+- Each output type gets appropriate handling
+
+## Execution Notes
+(filled by /reduce)
+
+## Outputs
+(filled by /reduce)
+```
+
+## Step 7: Update Queue
+
+Add the extract task entry to the queue file.
+
+**For YAML queues (ops/queue.yaml):**
+```yaml
+- id: {SOURCE_BASENAME}
+  type: extract
+  status: pending
+  source: "{FINAL_SOURCE}"
+  file: "{SOURCE_BASENAME}.md"
+  created: "{UTC timestamp}"
+  next_claim_start: {NEXT_CLAIM_START}
+```
+
+**For JSON queues (ops/queue/queue.json):**
+```json
+{
+  "id": "{SOURCE_BASENAME}",
+  "type": "extract",
+  "status": "pending",
+  "source": "{FINAL_SOURCE}",
+  "file": "{SOURCE_BASENAME}.md",
+  "created": "{UTC timestamp}",
+  "next_claim_start": {NEXT_CLAIM_START}
+}
+```
+
+**If no queue file exists:** Create one with the appropriate schema header (phase_order definitions) and this first task entry.
+
+## Step 8: Report
+
+```
+--=={ seed }==--
+
+Seeded: {SOURCE_BASENAME}
+Source: {original path} -> {FINAL_SOURCE}
+Archive folder: {ARCHIVE_DIR}
+Size: {line count} lines
+Content type: {detected type}
+
+Task file: ops/queue/{SOURCE_BASENAME}.md
+Claims will start at: {NEXT_CLAIM_START}
+Claim files will be: {SOURCE_BASENAME}-{NNN}.md (unique across vault)
+Queue: updated with extract task
+
+Next steps:
+  /ralph 1 --batch {SOURCE_BASENAME}     (extract claims)
+  /pipeline will handle this automatically
+```
+
+---
+
+## Why This Skill Exists
+
+Manual queue management is error-prone. This skill:
+- Ensures consistent task file format across batches
+- Handles claim numbering automatically (globally unique)
+- Checks for duplicates before creating unnecessary work
+- Moves sources to their permanent archive location immediately
+- Provides clear next steps for the user
+
+## Naming Convention
+
+Task files use the source basename for human readability:
+- Task file: `{source-basename}.md`
+- Claim files: `{source-basename}-{NNN}.md`
+- Summary: `{source-basename}-summary.md`
+- Archive folder: `{date}-{source-basename}/`
+
+Claim numbers (NNN) are globally unique across all batches, ensuring every filename is unique vault-wide. This is required because wiki links resolve by filename, not path.
+
+## Source Handling Patterns
+
+**{DOMAIN:inbox} source (most common):**
+```
+{DOMAIN:inbox}/research/article.md
+    | /seed
+    v
+ops/queue/archive/2026-01-30-article/article.md  <- source moved here
+ops/queue/article.md                               <- task file created
+```
+
+**Living doc (outside {DOMAIN:inbox}):**
+```
+CLAUDE.md -> stays as CLAUDE.md (no move)
+ops/queue/archive/2026-01-30-claude-md/           <- folder still created
+ops/queue/claude-md.md                             <- task file created
+```
+
+When /archive-batch runs later, it moves task files into the existing archive folder and generates a summary.
+
+---
+
+## Edge Cases
+
+**Source outside {DOMAIN:inbox}:** Works — source stays in place, archive folder is created for task files only.
+
+**No queue file:** Create `ops/queue/queue.yaml` (or `.json`) with schema header and this first entry.
+
+**Large source (2500+ lines):** Note in output: "Large source ({N} lines) -- /reduce will chunk automatically."
+
+**Source is a URL or non-file:** Report error: "/seed requires a file path."
+
+**No ops/derivation-manifest.md:** Use universal vocabulary for all output.
+
+---
+
+## Critical Constraints
+
+**never:**
+- Skip duplicate detection (prevents wasted processing)
+- Move a source that is not in {DOMAIN:inbox} (living docs stay in place)
+- Reuse claim numbers from previous batches (globally unique is required)
+- Create a task file without updating the queue (both must happen together)
+
+**always:**
+- Ask before proceeding when duplicates are detected
+- Create the archive folder even for living docs (task files need it)
+- Use the archived path (not original) in the task file for {DOMAIN:inbox} sources
+- Report next steps clearly so the user knows what to do next
+- Compute next_claim_start from both queue AND archive (not just one)

package/skill-sources/seed/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "knowledge-seed",
+  "description": "Add a source file to the processing queue. Checks for duplicates, creates archive folder, moves source from inbox, creates extract task, and updates queue.",
+  "version": "0.4.0",
+  "author": "arscontexta",
+  "tags": ["knowledge-management", "pipeline", "processing"],
+  "entry": "SKILL.md",
+  "platform_hints": {
+    "claude-code": {
+      "context": "fork",
+      "model": "opus"
+    },
+    "openclaw": {
+      "type": "external"
+    }
+  }
+}

package/skill-sources/stats/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: stats
+description: Show vault statistics and knowledge graph metrics. Provides a shareable snapshot of vault health, growth, and progress. Triggers on "/stats", "vault stats", "show metrics", "how big is my vault".
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+user-invocable: true
+context: fork
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[--share] — optional flag for compact shareable output"
+---
+
+## Runtime Configuration (Step 0 — before any processing)
+
+Read these files to configure domain-specific behavior:
+
+1. **`ops/derivation-manifest.md`** — vocabulary mapping
+   - Use `vocabulary.notes` for the notes folder name
+   - Use `vocabulary.note` / `vocabulary.note_plural` for note type references
+   - Use `vocabulary.topic_map` / `vocabulary.topic_map_plural` for MOC references
+   - Use `vocabulary.inbox` for the inbox folder name
+   - Use `vocabulary.notes_collection` for semantic search collection name
+
+2. **`ops/config.yaml`** — processing depth, automation settings
+
+If no derivation file exists, use universal terms (notes, MOCs, etc.).
+
+---
+
+## EXECUTE NOW
+
+**Target: $ARGUMENTS**
+
+Parse immediately:
+- If target contains `--share`: output compact shareable format after full stats
+- If target is empty: output full stats display
+- If target names a specific category (e.g., "health", "growth", "pipeline"): show only that category
+
+**START NOW.** Collect metrics and present them.
+
+---
+
+## Philosophy
+
+**Make the invisible visible.**
+
+The knowledge graph grows silently. Without metrics, the user cannot tell whether their system is healthy, growing, stagnating, or fragmenting. /stats provides a snapshot that makes growth tangible — numbers that show progress, health indicators that catch problems, and trends that reveal trajectory.
+
+The output should make the user feel informed, not overwhelmed. Metrics are evidence, not judgment. "12 orphans" is a fact. What to DO about it belongs to /graph or /{vocabulary.cmd_reflect}.
+
+---
+
+## Step 1: Collect Metrics
+
+Gather all metrics. Run these checks in parallel where possible to minimize latency.
+
+### 1a. Knowledge Graph Metrics
+
+```bash
+NOTES_DIR="{vocabulary.notes}"
+
+# Note count (excluding MOCs)
+TOTAL_FILES=$(ls -1 "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+MOC_COUNT=$(grep -rl '^type: moc' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+NOTE_COUNT=$((TOTAL_FILES - MOC_COUNT))
+
+# Connection count (all wiki links across notes/)
+LINK_COUNT=$(grep -ohP '\[\[[^\]]+\]\]' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+
+# Average connections per note
+if [[ "$NOTE_COUNT" -gt 0 ]]; then
+  AVG_LINKS=$(echo "scale=1; $LINK_COUNT / $NOTE_COUNT" | bc)
+else
+  AVG_LINKS="0"
+fi
+
+# Topic count (unique values in topics: fields)
+TOPIC_COUNT=$(grep -ohP '^\s*-\s*"\[\[([^\]]+)\]\]"' "$NOTES_DIR"/*.md 2>/dev/null | sort -u | wc -l | tr -d ' ')
+
+# Link density
+if [[ "$NOTE_COUNT" -gt 1 ]]; then
+  POSSIBLE=$((NOTE_COUNT * (NOTE_COUNT - 1)))
+  DENSITY=$(echo "scale=4; $LINK_COUNT / $POSSIBLE" | bc)
+else
+  DENSITY="N/A"
+fi
+```
+
+### 1b. Health Metrics
+
+```bash
+# Orphan count (notes with zero incoming links)
+ORPHAN_COUNT=0
+for f in "$NOTES_DIR"/*.md; do
+  NAME=$(basename "$f" .md)
+  grep -q '^type: moc' "$f" 2>/dev/null && continue
+  INCOMING=$(grep -rl "\[\[$NAME\]\]" "$NOTES_DIR"/ 2>/dev/null | grep -v "$f" | wc -l | tr -d ' ')
+  [[ "$INCOMING" -eq 0 ]] && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+done
+
+# Dangling link count
+DANGLING_COUNT=$(grep -ohP '\[\[([^\]]+)\]\]' "$NOTES_DIR"/*.md 2>/dev/null | sort -u | while read -r link; do
+  NAME=$(echo "$link" | sed 's/\[\[//;s/\]\]//')
+  [[ ! -f "$NOTES_DIR/$NAME.md" ]] && echo "$NAME"
+done | wc -l | tr -d ' ')
+
+# Schema compliance (% of notes with required fields: description, topics)
+MISSING_DESC=$(grep -rL '^description:' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+MISSING_TOPICS=$(grep -rL '^topics:' "$NOTES_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+SCHEMA_ISSUES=$((MISSING_DESC + MISSING_TOPICS))
+if [[ "$TOTAL_FILES" -gt 0 ]]; then
+  # Notes with BOTH required fields
+  COMPLIANT=$((TOTAL_FILES - MISSING_DESC))
+  COMPLIANCE=$(echo "scale=0; $COMPLIANT * 100 / $TOTAL_FILES" | bc)
+else
+  COMPLIANCE="N/A"
+fi
+
+# MOC coverage
+COVERED=0
+for f in "$NOTES_DIR"/*.md; do
+  NAME=$(basename "$f" .md)
+  grep -q '^type: moc' "$f" 2>/dev/null && continue
+  if grep -rl '^type: moc' "$NOTES_DIR"/*.md 2>/dev/null | xargs grep -l "\[\[$NAME\]\]" >/dev/null 2>&1; then
+    COVERED=$((COVERED + 1))
+  fi
+done
+if [[ "$NOTE_COUNT" -gt 0 ]]; then
+  COVERAGE=$(echo "scale=0; $COVERED * 100 / $NOTE_COUNT" | bc)
+else
+  COVERAGE="N/A"
+fi
+```
+
+### 1c. Pipeline Metrics
+
+```bash
+# Inbox items
+INBOX_COUNT=$(find {vocabulary.inbox}/ -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+
+# Queue pending (check both YAML and JSON formats)
+QUEUE_FILE=""
+if [[ -f "ops/queue/queue.yaml" ]]; then
+  QUEUE_FILE="ops/queue/queue.yaml"
+  QUEUE_PENDING=$(grep -c 'status: pending' "$QUEUE_FILE" 2>/dev/null || echo 0)
+  QUEUE_DONE=$(grep -c 'status: done' "$QUEUE_FILE" 2>/dev/null || echo 0)
+elif [[ -f "ops/queue/queue.json" ]]; then
+  QUEUE_FILE="ops/queue/queue.json"
+  QUEUE_PENDING=$(grep -c '"status": "pending"' "$QUEUE_FILE" 2>/dev/null || echo 0)
+  QUEUE_DONE=$(grep -c '"status": "done"' "$QUEUE_FILE" 2>/dev/null || echo 0)
+else
+  QUEUE_PENDING=0
+  QUEUE_DONE=0
+fi
+
+# Processed ratio (notes vs inbox)
+TOTAL_CONTENT=$((NOTE_COUNT + INBOX_COUNT))
+if [[ "$TOTAL_CONTENT" -gt 0 ]]; then
+  PROCESSED_PCT=$(echo "scale=0; $NOTE_COUNT * 100 / $TOTAL_CONTENT" | bc)
+else
+  PROCESSED_PCT="N/A"
+fi
+```
+
+### 1d. Growth Metrics
+
+```bash
+# This week's growth (notes with created: date within last 7 days)
+WEEK_AGO=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d 2>/dev/null)
+if [[ -n "$WEEK_AGO" ]]; then
+  THIS_WEEK_NOTES=$(grep -rl "^created: " "$NOTES_DIR"/*.md 2>/dev/null | while read -r f; do
+    CREATED=$(grep '^created:' "$f" | head -1 | awk '{print $2}')
+    [[ "$CREATED" > "$WEEK_AGO" || "$CREATED" == "$WEEK_AGO" ]] && echo "$f"
+  done | wc -l | tr -d ' ')
+else
+  THIS_WEEK_NOTES="?"
+fi
+
+# This week's connections (approximate — count links in recently created notes)
+if [[ "$THIS_WEEK_NOTES" -gt 0 && -n "$WEEK_AGO" ]]; then
+  THIS_WEEK_LINKS=$(grep -rl "^created: " "$NOTES_DIR"/*.md 2>/dev/null | while read -r f; do
+    CREATED=$(grep '^created:' "$f" | head -1 | awk '{print $2}')
+    [[ "$CREATED" > "$WEEK_AGO" || "$CREATED" == "$WEEK_AGO" ]] && grep -oP '\[\[[^\]]+\]\]' "$f" 2>/dev/null
+  done | wc -l | tr -d ' ')
+else
+  THIS_WEEK_LINKS="?"
+fi
+```
+
+### 1e. System Metrics
+
+```bash
+# Self space
+if [[ -d "self/" ]]; then
+  SELF_FILES=$(find self/ -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+  SELF_STATUS="enabled ($SELF_FILES files)"
+else
+  SELF_STATUS="disabled"
+fi
+
+# Methodology notes
+METHODOLOGY_COUNT=$(ls -1 ops/methodology/*.md 2>/dev/null | wc -l | tr -d ' ')
+
+# Observations pending
+OBS_PENDING=$(grep -rl '^status: pending' ops/observations/ 2>/dev/null | wc -l | tr -d ' ')
+
+# Tensions pending
+TENSION_PENDING=$(grep -rl '^status: open\|^status: pending' ops/tensions/ 2>/dev/null | wc -l | tr -d ' ')
+
+# Sessions captured
+SESSION_COUNT=$(ls -1 ops/sessions/*.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+Adapt all directory names to domain vocabulary. Skip checks for directories that do not exist — report "N/A" instead of errors.
+
+---
+
+## Step 2: Format Output
+
+### Full Output (default)
+
+Generate a progress bar for the Processed metric:
+
+```
+Progress bar calculation:
+  filled = PROCESSED_PCT / 5 (number of = characters out of 20)
+  empty = 20 - filled
+  bar = [===...   ] PCT%
+```
+
+```
+--=={ stats }==--
+
+  Knowledge Graph
+  ===============
+  {vocabulary.note_plural}:  [NOTE_COUNT]
+  Connections:               [LINK_COUNT] (avg [AVG_LINKS] per {vocabulary.note})
+  {vocabulary.topic_map_plural}:   [MOC_COUNT] (covering [COVERAGE]% of {vocabulary.note_plural})
+  Topics:                    [TOPIC_COUNT]
+
+  Health
+  ======
+  Orphans:      [ORPHAN_COUNT]
+  Dangling:     [DANGLING_COUNT]
+  Schema:       [COMPLIANCE]% compliant
+
+  Pipeline
+  ========
+  Processed:    [==============      ] [PROCESSED_PCT]%
+  Inbox:        [INBOX_COUNT] items
+  Queue:        [QUEUE_PENDING] pending tasks
+
+  Growth
+  ======
+  This week:    +[THIS_WEEK_NOTES] {vocabulary.note_plural}, +[THIS_WEEK_LINKS] connections
+  Graph density: [DENSITY]
+
+  System
+  ======
+  Self space:      [SELF_STATUS]
+  Methodology:     [METHODOLOGY_COUNT] learned patterns
+  Observations:    [OBS_PENDING] pending
+  Tensions:        [TENSION_PENDING] open
+  Sessions:        [SESSION_COUNT] captured
+
+  Generated by Ars Contexta v1.6
+```
+
+### Interpretation Notes
+
+After the stats block, add brief interpretation for any notable findings:
+
+| Condition | Note |
+|-----------|------|
+| ORPHAN_COUNT > 0 | "[N] orphan {vocabulary.note_plural} — run `/graph health` for details" |
+| DANGLING_COUNT > 0 | "[N] dangling links — run `/graph health` to identify broken links" |
+| COMPLIANCE < 90 | "Schema compliance below 90% — some {vocabulary.note_plural} missing required fields" |
+| OBS_PENDING >= 10 | "[N] pending observations — consider running /{vocabulary.rethink}" |
+| TENSION_PENDING >= 5 | "[N] open tensions — consider running /{vocabulary.rethink}" |
+| DENSITY < 0.02 | "Graph density is low — connections are thin. Run /{vocabulary.cmd_reflect} to strengthen the network" |
+| PROCESSED_PCT < 50 | "More content in inbox than in {vocabulary.notes}/ — consider processing backlog" |
+| THIS_WEEK_NOTES == 0 | "No new {vocabulary.note_plural} this week" |
+
+Only show interpretation notes when conditions are notable. A healthy vault gets just the stats, no warnings.
+
+---
+
+## Step 3: Shareable Format (--share flag)
+
+If invoked with `--share`, output a compact markdown block suitable for sharing on social media or in documentation:
+
+```markdown
+## My Knowledge Graph
+
+- **[NOTE_COUNT]** {vocabulary.note_plural} with **[LINK_COUNT]** connections (avg [AVG_LINKS] per {vocabulary.note})
+- **[MOC_COUNT]** {vocabulary.topic_map_plural} covering [COVERAGE]% of {vocabulary.note_plural}
+- Schema compliance: [COMPLIANCE]%
+- This week: +[THIS_WEEK_NOTES] {vocabulary.note_plural}, +[THIS_WEEK_LINKS] connections
+- Graph density: [DENSITY]
+
+*Built with [Ars Contexta](https://github.com/arscontexta) v1.6*
+```
+
+The shareable format:
+- Omits health warnings (positive framing for sharing)
+- Omits pipeline state (internal detail)
+- Omits system metrics (internal detail)
+- Includes only growth-positive metrics
+- Always includes the Ars Contexta attribution line
+
+---
+
+## Step 4: Trend Analysis (when history exists)
+
+If previous /stats runs are logged in `ops/stats-history.yaml` (or similar), compare current metrics against the last snapshot:
+
+```
+  Trend (vs last check):
+    {vocabulary.note_plural}: [N] (+[delta] since [date])
+    Connections:              [N] (+[delta])
+    Density:                  [N] ([up/down/stable])
+    Orphans:                  [N] ([improved/worsened/stable])
+```
+
+If no history exists, skip trend analysis. Do NOT create the history file — that is /health's responsibility.
+
+---
+
+## Edge Cases
+
+### Empty Vault (0 notes)
+
+Show zeros gracefully:
+```
+--=={ stats }==--
+
+  Your knowledge graph is new. Start capturing to see it grow.
+
+  Knowledge Graph
+  ===============
+  {vocabulary.note_plural}:  0
+  Connections:               0
+  {vocabulary.topic_map_plural}:   0
+  Topics:                    0
+
+  Generated by Ars Contexta v1.6
+```
+
+Do not show health, pipeline, growth, or system sections for an empty vault — they would all be zeros or N/A.
+
+### No Queue System
+
+Skip the Pipeline section entirely. Do not show an error.
+
+### No Self Space
+
+Show "disabled" for self space line. Do not show an error.
+
+### No ops/derivation-manifest.md
+
+Use universal vocabulary (notes, MOCs, etc.). All metrics work identically.
+
+### Very Large Vault (500+ notes)
+
+The orphan and MOC coverage checks may be slow for large vaults. If {vocabulary.notes}/ has >200 files:
+1. Run orphan detection with a simpler heuristic (check only for presence in any MOC, not full backlink scan)
+2. Note: "Metrics approximate for large vault. Run /graph health for precise analysis."
+
+### Platform-Specific Date Commands
+
+macOS uses `date -v-7d`, Linux uses `date -d '7 days ago'`. The script tries both. If neither works, report "?" for growth metrics instead of failing.