docs(readme): add Detection Rules as Memory section

[rolandpg]

Follow-up to #70. Adds a README section documenting the Sigma + YARA first-class primitives for readers who don't click through to the blog post.

What's included

• One-paragraph explainer + reference to the shared DetectionRule supertype
• Upstream-spec references (SigmaHQ JSON schema, CCCS YARA metadata, YARA docs)
• Python API snippet (ingest_sigma + ingest_yara)
• CLI usage (single-file, bulk-directory, --dry-run)
• Honest framing of the LLM rule explainer: synchronous on-demand in v1, async enrichment-queue wiring is v1.1 work (matches detection/explainer.py:7-9 docstring)

Voice + scope

• Brand-voice compliant: no emoji, no exclamation marks, no hype adjectives ("powerful", "blazing-fast")
• No comparative framing against Mem0 / Graphiti / LangMem
• No SOC Prime / DetectFlow endorsement claims
• Matches the existing ## Quick Start / ## How It Works / ATHF bridge voice
• Placement: between ## MCP Server (Claude Code) and ## Integrations (alongside the ATHF bridge row)

Related

• feat(detection): Phase 2 scaffold — Sigma + YARA first-class (draft, Phase 3 fills impls) #70 — source PR (merged e6dcfa4)
• Add typed DetectionMeta extension to MemoryNote.Metadata #71 — follow-on: typed DetectionMeta extension
• MemoryManager.remember(sync=True) dominates bulk ingest; YARA p95 plyara tail #72 — follow-on: remember(sync=True) bulk-ingest bottleneck + plyara p95
• Tighten CCCS metadata regexes (SEC-6 / SEC-7) #73 — follow-on: CCCS YARA regex tightening

[Copilot]

Pull request overview

Adds a new README section that documents Sigma + YARA “detection rules as memory” to make the detection-rule primitives discoverable without the blog post.

Changes:

• Introduces a “Detection Rules as Memory (Sigma + YARA)” section explaining rule ingest and ontology/graph integration
• Adds Python API and CLI usage examples for Sigma/YARA ingest (including --dry-run)
• Adds references to upstream specs and documents explainer behavior + rate limiting

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The statement that a “single rule UUID is addressable across both formats” looks inaccurate. In code, Sigma rule IDs come from the Sigma id field (or a sigma_<hash> fallback) while YARA uses CCCS meta.id (or a yara_<hash> fallback), so there isn’t a shared cross-format UUID namespace—only a shared DetectionRule field contract. Consider rephrasing to say both formats share the DetectionRule interface/fields rather than implying the same UUID identifies the same rule in both formats.

Suggested change

Sigma and YARA rules are first-class memory primitives. Parse, validate, and ingest a rule and its tags become graph edges: MITRE ATT&CK techniques, CVEs, threat-actor aliases, tools, and malware families resolve against the same ontology as every other note. A shared `DetectionRule` supertype carries `SigmaRule` and `YaraRule` subtypes, so a single rule UUID is addressable across both formats.

Sigma and YARA rules are first-class memory primitives. Parse, validate, and ingest a rule and its tags become graph edges: MITRE ATT&CK techniques, CVEs, threat-actor aliases, tools, and malware families resolve against the same ontology as every other note. A shared `DetectionRule` supertype carries `SigmaRule` and `YaraRule` subtypes, so both formats share the same rule interface and fields even though each format keeps its own rule identifier.

[Copilot]

This paragraph claims tags become graph edges for “tools” and “malware families”, but the current mapping only upgrades Sigma attack.s#### tags to Malware and doesn’t emit a distinct Tool entity type (and YARA tag resolution only emits AttackPattern, Vulnerability, ThreatActor, or YaraTag). To avoid over-promising, consider narrowing the wording to what’s actually emitted today (e.g., ATT&CK techniques, CVEs, ATT&CK group/software IDs, and generic tags).

Suggested change

Sigma and YARA rules are first-class memory primitives. Parse, validate, and ingest a rule and its tags become graph edges: MITRE ATT&CK techniques, CVEs, threat-actor aliases, tools, and malware families resolve against the same ontology as every other note. A shared `DetectionRule` supertype carries `SigmaRule` and `YaraRule` subtypes, so a single rule UUID is addressable across both formats.

Sigma and YARA rules are first-class memory primitives. Parse, validate, and ingest a rule and its tags become graph edges for currently supported mappings such as MITRE ATT&CK techniques, CVEs, ATT&CK group/software IDs, and generic tags, all resolved against the same ontology as every other note. A shared `DetectionRule` supertype carries `SigmaRule` and `YaraRule` subtypes, so a single rule UUID is addressable across both formats.

[Copilot]

The explainer output described here (“intent, key fields, evasion notes…”) doesn’t match the current RuleExplanation schema in zettelforge.detection.explainer, which returns fields like summary, mechanism, threat_model, false_positive_patterns, related_techniques, and confidence. Suggest updating the README wording to match the actual keys so users don’t build against fields that aren’t produced.

Suggested change

An LLM rule explainer (`zettelforge.detection.explainer.explain`) produces a structured JSON summary -- intent, key fields, evasion notes, false-positive hypotheses -- for any `DetectionRule`. It runs synchronously on demand in v1; async enrichment-queue wiring is v1.1. Rate-limited via `ZETTELFORGE_EXPLAIN_RPM` (default 60 calls/minute).

An LLM rule explainer (`zettelforge.detection.explainer.explain`) produces a structured JSON summary for any `DetectionRule`, including fields such as `summary`, `mechanism`, `threat_model`, `false_positive_patterns`, `related_techniques`, and `confidence`. It runs synchronously on demand in v1; async enrichment-queue wiring is v1.1. Rate-limited via `ZETTELFORGE_EXPLAIN_RPM` (default 60 calls/minute).