/minutes-graph

If the user explicitly says "build" / "rebuild" / "refresh the graph" → Phase 1 (build mode).

Otherwise → Phase 2 (query mode). Query mode auto-builds the index if it doesn't exist, and incrementally refreshes it if new meetings exist since the last build.

Detect company/product queries upfront. If the user's question mentions a specific company name, product, brand, or anything that wouldn't be in standard meeting frontmatter (e.g., "Stripe", "Notion", "the deal with Acme"), tell them upfront — before any building happens — that this needs deep extraction:

"That query is about a company/product, which isn't in standard meeting frontmatter. I'd need to deep-scan transcripts (~<estimate> seconds for <N> meetings) to answer. Continue, or rephrase to use topics/people that are already indexed?"

This avoids the worst flow: build → discover the data isn't there → ask user → rebuild.

Phase 1: Build the index via the bundled helper script

The index lives at ~/.minutes/graph/index.json. Use the bundled graph_build.py script — do not try to walk meeting files or parse YAML frontmatter in-context. The script is deterministic, fast, atomic, and handles all the edge cases (incremental rebuilds, garbage filtering, name disambiguation, augmentation from minutes people --json).

Always warn before building, even on the auto-trigger path. Users hate commands that hang silently more than they hate one-line confirmations:

"Building entity graph from <N> meetings. The frontmatter-only path is fast (a few seconds for hundreds of meetings). Continue? (Ctrl+C to abort)"

To get the meeting count for the warning, use Glob on the meetings dir from minutes paths.

Run the script:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/minutes-graph/scripts/graph_build.py" --incremental

Defaults:

• --meetings-dir defaults to output_dir from minutes paths
• --output defaults to ~/.minutes/graph/index.json
• --incremental skips the rebuild entirely if no meeting files have been modified since the last build (the common case after the first build)

The script prints a one-line summary JSON to stdout:

{"status": "ok", "meeting_count": 142, "person_count": 12, "topic_count": 38, "output": "/Users/.../index.json"}

Or {"status": "fresh", ...} if --incremental found nothing to rebuild.

What the script does, in order:

1. Walks every meeting file in the meetings directory
2. Parses the YAML frontmatter using a small line-based extractor (no PyYAML dep)
3. Extracts: date, attendees (display names), people (wikilink slugs), tags, and decisions[].topic — all the entity-relevant fields the real meeting schema actually has
4. Filters out none/null/~ topic values that show up in some malformed meetings
5. When attendees and people have the same length, zips them positionally to map each slug to its display name (gives mat → Mat S., etc.)
6. Builds people-people, people-topic, and topic-topic co-occurrence within each meeting
7. Runs minutes people --json and merges its top_topics, open_commitments, score, losing_touch fields into the people entries it already built
8. Filters diarization noise (unknown-speaker, speaker-3, etc.) out of the final people index
9. Picks a canonical display name for each person using a "looks human" heuristic (capital letter + space wins; lowercase slug-style loses)
10. Atomically writes the index to JSON (temp file + rename)

What's NOT in the default build: companies and products. Some real meetings do have an entities: block in their frontmatter — the current schema looks like: