mdcontext 0.0.1 → 0.2.0

package/research/dogfood/strategy-a/a1-docs.md

@@ -0,0 +1,226 @@
+# Report: A1 - Spec Analyst
+
+## Mission
+
+Extract the current spec's structure, key claims, and design decisions from docs/
+
+## Command Log
+
+| #   | Command                                                                              | Purpose                    | Result                                  | Useful? |
+| --- | ------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------- | ------- |
+| 1   | `mdcontext --help`                                                                   | Learn tool                 | Full command list with examples         | Yes     |
+| 2   | `mdcontext index --help`                                                             | Learn index options        | Options for --embed, --watch, --force   | Yes     |
+| 3   | `mdcontext search --help`                                                            | Learn search options       | Boolean ops, context lines, modes       | Yes     |
+| 4   | `mdcontext context --help`                                                           | Learn context options      | Token budgets, section filtering        | Yes     |
+| 5   | `mdcontext index --force --no-embed`                                                 | Index workspace            | 23 docs, 922 sections, 535ms            | Yes     |
+| 6   | `mdcontext tree`                                                                     | List all markdown files    | 23 files including 10 in docs/          | Yes     |
+| 7   | `mdcontext tree docs/00-README.md`                                                   | Show doc outline           | 9 sections, 1637 tokens                 | Yes     |
+| 8   | `mdcontext tree docs/01-ARCHITECTURE.md`                                             | Architecture outline       | 49 sections, 5037 tokens                | Yes     |
+| 9   | `mdcontext tree docs/02-PRIMITIVES.md`                                               | Primitives outline         | 67 sections, 6803 tokens                | Yes     |
+| 10  | `mdcontext tree docs/03-ORG_WORKSPACE_MODEL.md`                                      | Org/Workspace outline      | 52 sections, 5360 tokens                | Yes     |
+| 11  | `mdcontext tree docs/04-EXECUTION_MODEL.md`                                          | Execution outline          | 63 sections, 7418 tokens                | Yes     |
+| 12  | `mdcontext tree docs/05-MEMORY_MODEL.md`                                             | Memory outline             | 56 sections, 6848 tokens                | Yes     |
+| 13  | `mdcontext tree docs/06-WORKFLOWS.md`                                                | Workflows outline          | 65 sections, 8541 tokens                | Yes     |
+| 14  | `mdcontext tree docs/07-EXAMPLE_WORKFLOWS.md`                                        | Examples outline           | 55 sections, 14423 tokens               | Yes     |
+| 15  | `mdcontext context docs/00-README.md -t 3000`                                        | Get README summary         | Full content with 50% reduction         | Yes     |
+| 16  | `mdcontext context docs/01-ARCHITECTURE.md --section "Architectural Overview"`       | Get overview               | Core separation of concerns             | Yes     |
+| 17  | `mdcontext context docs/01-ARCHITECTURE.md --section "Why This Architecture Works"`  | Get justification          | 6 key reasons                           | Yes     |
+| 18  | `mdcontext search "human control"`                                                   | Find human control theme   | 10 results across docs                  | Yes     |
+| 19  | `mdcontext search "immutable"`                                                       | Find immutability theme    | 10 results                              | Yes     |
+| 20  | `mdcontext search "workspace"`                                                       | Find workspace concept     | 5 results                               | Yes     |
+| 21  | `mdcontext search "checkpoint"`                                                      | Find checkpoint references | 8 results                               | Yes     |
+| 22  | `mdcontext search "safety"`                                                          | Find safety theme          | 5 results                               | Yes     |
+| 23  | `mdcontext context docs/01-ARCHITECTURE.md --section "Architectural Invariants"`     | Get invariants             | 8 system invariants                     | Yes     |
+| 24  | `mdcontext context docs/02-PRIMITIVES.md --section "Summary"`                        | Get primitives summary     | Minimal primitive philosophy            | Yes     |
+| 25  | `mdcontext context docs/05-MEMORY_MODEL.md --section "Memory Philosophy"`            | Get memory philosophy      | Memory defined as derived understanding | Yes     |
+| 26  | `mdcontext context docs/05-MEMORY_MODEL.md --section "Why This Model Works"`         | Get memory justification   | Enables/Prevents/Supports/Scales        | Yes     |
+| 27  | `mdcontext context docs/06-WORKFLOWS.md --section "Workflow Philosophy"`             | Get workflow philosophy    | Guidance, not law                       | Yes     |
+| 28  | `mdcontext search "three-layer"`                                                     | Find memory layers         | 5 results                               | Yes     |
+| 29  | `mdcontext context docs/05-MEMORY_MODEL.md --section "The Three-Layer Architecture"` | Get layer details          | Event/Status/Semantic layers            | Yes     |
+| 30  | `mdcontext search '"execution context"'`                                             | Find execution contexts    | 5 results (exact phrase)                | Yes     |
+| 31  | `mdcontext search "parallel exploration"`                                            | Find parallel work         | 5 results                               | Yes     |
+| 32  | `mdcontext search "cost"`                                                            | Find cost model            | 5 results                               | Yes     |
+| 33  | `mdcontext search "Control Plane"`                                                   | Find control plane         | 5 results                               | Yes     |
+| 34  | `mdcontext context docs/02-PRIMITIVES.md --section "Control Plane"`                  | Get control plane details  | Full primitive definition               | Yes     |
+| 35  | `mdcontext search "time travel"`                                                     | Find time travel           | 5 results                               | Yes     |
+| 36  | `mdcontext search "branching"`                                                       | Find branching             | 5 results                               | Yes     |
+| 37  | `mdcontext context docs/05-MEMORY_MODEL.md --section "Time Travel"`                  | Get time travel details    | Query-based, not feature                | Yes     |
+| 38  | `mdcontext search "guarantee"`                                                       | Find guarantees            | 8 results                               | Yes     |
+| 39  | `mdcontext context docs/04-EXECUTION_MODEL.md --section "Guarantees"`                | Get execution guarantees   | 7 explicit guarantees                   | Yes     |
+| 40  | `mdcontext stats`                                                                    | Get index statistics       | 23 docs, 178K tokens, 922 sections      | Yes     |
+
+## Findings
+
+### Document Structure (docs/ folder)
+
+The docs/ folder contains 10 markdown files forming a comprehensive specification:
+
+1. **00-README.md** (1,637 tokens) - Overview, principles, differentiators
+2. **01-ARCHITECTURE.md** (5,037 tokens) - 17 sections covering full system architecture
+3. **02-PRIMITIVES.md** (6,803 tokens) - 20 formal primitive definitions
+4. **03-ORG_WORKSPACE_MODEL.md** (5,360 tokens) - 13 sections on org/workspace
+5. **04-EXECUTION_MODEL.md** (7,418 tokens) - 18 sections on execution
+6. **05-MEMORY_MODEL.md** (6,848 tokens) - 17 sections on three-layer memory
+7. **06-WORKFLOWS.md** (8,541 tokens) - 19 sections on workflow system
+8. **07-EXAMPLE_WORKFLOWS.md** (14,423 tokens) - 5 detailed example workflows
+9. **HumanWork-Evolution.md** - Evolution/roadmap document
+10. **LETTA_INTEGRATION_PLAN.md** - Integration planning
+
+Total: ~56,000 tokens of spec content in docs/
+
+### Key Discoveries
+
+#### Core Philosophy
+
+The system is named **HumanWork** and is explicitly designed as a "human work operating system, not an agent orchestrator."
+
+> "The system helps humans think better - it never decides for them."
+> Source: docs/00-README.md, Philosophy section
+
+#### Design Decision: Separation of Concerns
+
+> "HumanWork separates concerns explicitly:
+>
+> - **Execution**: agents performing steps within bounded contexts
+> - **Authority**: humans controlling execution via a preemptive control plane
+> - **History**: immutable records of what occurred
+> - **Understanding**: derived state and semantic views"
+>   Source: docs/01-ARCHITECTURE.md, Section 1
+
+#### Design Decision: Preemptive Control Plane
+
+> "The Control Plane has **preemptive authority** over all execution. No agent, workflow, or job may refuse a control plane directive."
+> Source: docs/01-ARCHITECTURE.md, Section 3
+
+Control actions: pause, resume, cancel, reassign, modify_metadata, inject_step, fork, terminate
+
+#### Design Decision: Three-Layer Memory
+
+> "Workspace Memory consists of three orthogonal, composable layers:
+>
+> - Event / Fact Memory (Ground Truth)
+> - Status Memory (Operational Truth)
+> - Semantic Memory (Understanding)"
+>   Source: docs/05-MEMORY_MODEL.md, Section 2
+
+> "Memory is **not**: Chat logs, Raw execution logs, Agent recall, Hidden embeddings"
+> Source: docs/05-MEMORY_MODEL.md, Section 1
+
+#### Design Decision: Immutability as Foundation
+
+> "All meaningful system activity is recorded as immutable facts. Execution advances by appending new records rather than mutating existing state. Time travel and branching are natural consequences of the data model."
+> Source: docs/00-README.md, Core Principles
+
+#### Design Decision: Workflows as Guidance
+
+> "In HumanWork, workflows are: **Reusable coordination patterns that shape how work unfolds, without prescribing execution logic.**
+> Workflows are **guidance**, not law."
+> Source: docs/06-WORKFLOWS.md, Section 1
+
+#### Architectural Invariants (8 Hard Rules)
+
+> - No hidden mutable state
+> - No irreversible execution (recordable and replayable)
+> - No unobservable progress
+> - No agent-owned memory
+> - No loss of human authority
+> - No concurrent mutation of the same scope
+> - No execution without a Workspace
+> - No automatic flow from Org to Workspace
+>   Source: docs/01-ARCHITECTURE.md, Section 14
+
+#### Execution Guarantees
+
+> - **Single-scope coherence**: no concurrent mutation of the same scope
+> - **Human control**: execution always interruptible
+> - **Deterministic replay**: all execution is reproducible from records
+> - **Cost attribution**: every execution traceable to Workspace and Job
+> - **No hidden state**: all context is external and inspectable
+> - **Agent replaceability**: work continues regardless of agent instance
+> - **Workflow interoperability**: external systems integrate cleanly
+>   Source: docs/04-EXECUTION_MODEL.md, Section 16
+
+### Relevant Quotes/Sections Found
+
+> "This is a human work operating system, not an agent orchestrator."
+> Source: docs/00-README.md, What You Get
+
+> "Time travel is **a query, not a feature**."
+> Source: docs/05-MEMORY_MODEL.md, Section 8
+
+> "The system favors clarity, safety, and trust over raw autonomy."
+> Source: docs/00-README.md, intro
+
+> "It is designed for work that unfolds over time: architecture reviews, security assessments, R&D exploration, planning sessions, and collaborative analysis."
+> Source: docs/00-README.md, intro
+
+### Themes Identified
+
+1. **Human Authority is Non-Negotiable**: Control plane is "always listening, preemptive", humans retain authority at all times, checkpoints enforce human control
+
+2. **Immutability as Foundation**: No hidden mutable state, append-only records, time travel and branching as natural consequences
+
+3. **Explicit Over Implicit**: Metadata-driven configuration, derived state for observability, no hidden embeddings or agent memory
+
+4. **Safety Without Bureaucracy**: Enterprise-grade safety, guaranteed interruptibility, audit trails without performance penalties
+
+5. **Scalability Through Configuration**: Scaling from individuals to enterprises is configuration change, not architectural change
+
+6. **Cost Visibility**: Cost attribution by default, workspace as cost boundary, traceable to Job/Workspace
+
+7. **Parallel Exploration**: Parallel hypotheses without conflicts, parallel execution with fan-out/fan-in patterns
+
+## Tool Evaluation
+
+### What Worked Well
+
+- **tree command**: Excellent for understanding document structure; token counts per section very helpful
+- **context --section**: Precise extraction of specific sections; very efficient
+- **search with boolean/phrase**: Quoted phrases and AND/OR worked well
+- **Token reduction**: context command showed "50% reduction" - useful compression
+- **stats**: Quick overview of index size and distribution
+- **index speed**: 535ms for 23 docs is fast
+
+### What Was Frustrating
+
+- **search from subdirectory failed**: `mdcontext search "..." docs/` returned "No index found" even though index existed - had to search from root
+- **No semantic search by default**: Required --embed flag and OPENAI_API_KEY; keyword search adequate but limited
+- **Context duplication**: `--section "Time Travel"` returned the same section twice (once as parent, once as subsection match)
+- **No way to search AND get context**: Search shows snippets but can't easily expand; had to follow up with context command
+
+### What Was Missing
+
+- **Cross-reference navigation**: No easy way to "find all sections that reference this concept"
+- **Diff between documents**: Can't compare two docs or see overlap
+- **Export/summarize all**: No "summarize everything in docs/" command
+- **Section numbering inconsistency**: tree shows "## 1. Section" but context uses "1.1" notation
+
+### Confidence Level
+
+[X] High
+
+I found all major structural elements, design decisions, and key claims. The tool provided efficient access to content without reading 56K tokens of raw markdown.
+
+### Would Use Again? (1-5)
+
+**4** - Very useful for exploration and targeted extraction. The tree+context+search workflow is effective. Lost a point for the subdirectory search bug and lack of semantic search out-of-box.
+
+## Time & Efficiency
+
+- Commands run: **40**
+- Tokens read via mdcontext: ~15,000 (estimated from context outputs)
+- Total docs tokens: 56,000+ in docs/ alone
+- Compared to reading all files: **much less** - approximately 25-30% of raw content needed to extract key information
+
+## Summary
+
+The HumanWork spec defines a comprehensive multi-agent orchestration system with:
+
+- **20 formal primitives** with explicit guarantees
+- **Three-layer memory model** (Event/Status/Semantic)
+- **Preemptive human control** via always-on Control Plane
+- **Immutable event sourcing** enabling time travel and branching
+- **Workflow as guidance** not enforcement
+- **8 architectural invariants** as hard system rules
+
+The mdcontext tool proved effective for navigating this large specification efficiently.

package/research/dogfood/strategy-a/a2-amorphic.md

@@ -0,0 +1,156 @@
+# Report: A2 - Amorphic Feedback Analyst
+
+## Mission
+
+Extract feedback, criticism, suggestions, and concerns from docs.amorphic/
+
+## Command Log
+
+| #   | Command                                                                                   | Purpose                      | Result                                                                                                                                                | Useful?     |
+| --- | ----------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| 1   | mdcontext --help                                                                          | Learn tool capabilities      | Showed commands: index, search, context, tree, links, backlinks, stats                                                                                | Yes         |
+| 2   | ls docs.amorphic/                                                                         | See available files          | 9 markdown files covering executive summary, failure analysis, architecture, collaboration, technical patterns, org transformation, future directions | Yes         |
+| 3   | mdcontext index --force                                                                   | Force index the directory    | Indexed 23 documents, 922 sections                                                                                                                    | Yes         |
+| 4   | mdcontext tree docs.amorphic/                                                             | List markdown files          | Confirmed 9 files in the folder                                                                                                                       | Yes         |
+| 5   | mdcontext tree docs.amorphic/00-INDEX.md                                                  | Document outline             | Showed 2 sections, 731 tokens                                                                                                                         | Yes         |
+| 6   | mdcontext search "feedback"                                                               | Find feedback mentions       | 10 results, 3 from docs.amorphic                                                                                                                      | Moderate    |
+| 7   | mdcontext search "criticism"                                                              | Find criticism               | Only 1 result (from SPEC.md)                                                                                                                          | No          |
+| 8   | mdcontext search "suggestion"                                                             | Find suggestions             | 10 results, limited docs.amorphic hits                                                                                                                | Moderate    |
+| 9   | mdcontext search "concern"                                                                | Find concerns                | 10 results, mostly from other docs                                                                                                                    | Moderate    |
+| 10  | mdcontext search "failure"                                                                | Find failure themes          | 10 results, strong docs.amorphic coverage                                                                                                             | Yes         |
+| 11  | mdcontext context docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md -t 4000              | Get full context summary     | Excellent summary of automation failures                                                                                                              | Very useful |
+| 12  | mdcontext search "problem"                                                                | Find problems identified     | 10 results, good docs.amorphic coverage                                                                                                               | Yes         |
+| 13  | mdcontext search "limitation"                                                             | Find limitations             | 3 results, 1 from docs.amorphic                                                                                                                       | Yes         |
+| 14  | mdcontext search "challenge"                                                              | Find challenges              | 10 results, 3 from docs.amorphic                                                                                                                      | Moderate    |
+| 15  | mdcontext search "risk"                                                                   | Find risks                   | 10 results, minimal docs.amorphic                                                                                                                     | Moderate    |
+| 16  | mdcontext context docs.amorphic/01-EXECUTIVE_SUMMARY.md -t 3000                           | Summary context              | 61% token reduction, key innovations extracted                                                                                                        | Very useful |
+| 17  | mdcontext tree docs.amorphic/03-ARCHITECTURAL_FOUNDATIONS.md                              | Document outline             | 6 major sections                                                                                                                                      | Yes         |
+| 18  | mdcontext context docs.amorphic/03-ARCHITECTURAL_FOUNDATIONS.md -t 3500                   | Architecture context         | Memory architecture, dynamic graphs, state management                                                                                                 | Very useful |
+| 19  | mdcontext context docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md -t 3500         | Collaboration context        | Authority gradient, collaboration modes, transparency                                                                                                 | Very useful |
+| 20  | mdcontext context docs.amorphic/08-FUTURE_IMPLICATIONS_AND_RESEARCH_DIRECTIONS.md -t 3000 | Future/research context      | Open questions, research frontiers                                                                                                                    | Very useful |
+| 21  | mdcontext search "improve"                                                                | Find improvement areas       | 10 results, 2 from docs.amorphic                                                                                                                      | Moderate    |
+| 22  | mdcontext search "issue"                                                                  | Find issues raised           | 10 results, mostly technical                                                                                                                          | Low         |
+| 23  | mdcontext search "question"                                                               | Find questions raised        | 10 results, 2 from docs.amorphic                                                                                                                      | Moderate    |
+| 24  | mdcontext context docs.amorphic/06-ORGANIZATIONAL_TRANSFORMATION.md -t 4000               | Org transformation           | Choreographic maturity, cultural shifts                                                                                                               | Very useful |
+| 25  | mdcontext context docs.amorphic/05-TECHNICAL_IMPLEMENTATION_PATTERNS.md -t 3000           | Technical patterns           | Primitive-first, memory infrastructure                                                                                                                | Very useful |
+| 26  | mdcontext search "should"                                                                 | Find prescriptive statements | 10 results, 2 from docs.amorphic                                                                                                                      | Moderate    |
+| 27  | mdcontext search "must"                                                                   | Find requirements            | 10 results, minimal docs.amorphic                                                                                                                     | Low         |
+| 28  | mdcontext search "handoff"                                                                | Find handoff discussion      | 10 results, 5 from docs.amorphic                                                                                                                      | Yes         |
+| 29  | mdcontext context docs.amorphic/\_0.BLURB.md -t 3000                                      | Get blurb context            | Very minimal output (100% reduction)                                                                                                                  | No          |
+| 30  | mdcontext search "brittle"                                                                | Find brittleness concerns    | 10 results, 5 from docs.amorphic                                                                                                                      | Yes         |
+| 31  | mdcontext search "open question"                                                          | Find open questions          | 4 results, 2 from docs.amorphic                                                                                                                       | Yes         |
+| 32  | mdcontext search "research"                                                               | Find research directions     | 10 results                                                                                                                                            | Moderate    |
+| 33  | mdcontext search "trust"                                                                  | Find trust discussions       | 10 results                                                                                                                                            | Moderate    |
+| 34  | mdcontext search "cost"                                                                   | Find cost concerns           | 10 results                                                                                                                                            | Moderate    |
+| 35  | mdcontext search "autonomy"                                                               | Find autonomy balance        | 10 results, 1 from docs.amorphic                                                                                                                      | Moderate    |
+| 36  | mdcontext search "evolution"                                                              | Find evolution themes        | 10 results, 2 from docs.amorphic                                                                                                                      | Moderate    |
+| 37  | mdcontext search "need"                                                                   | Find expressed needs         | 10 results                                                                                                                                            | Low         |
+| 38  | mdcontext context docs.amorphic/00-INDEX.md -t 2000                                       | Index overview               | Document structure overview                                                                                                                           | Moderate    |
+
+## Findings
+
+### Key Discoveries
+
+1. **The Handoff Problem is Central**: docs.amorphic identifies the "handoff problem" as THE core issue - friction between human creative processes and systematic execution. Current workflow tools create artificial boundaries that fragment work.
+
+2. **Pure Automation is Fundamentally Flawed for Knowledge Work**: The failure analysis document makes a strong case that automation fails not due to poor implementation but conceptual mismatch with knowledge work's nature.
+
+3. **Six Specific Failure Modes Identified**:
+   - Brittleness of Complete Systems (combinatorial rule explosion)
+   - Coordination Trap (multiplies rather than reduces overhead)
+   - Innovation Strangulation (automation-incompatible = avoided)
+   - Human Bottleneck Paradox (routing around humans creates new bottlenecks)
+   - Context Collapse (no mechanism for negotiation or doubt)
+   - Judgment Gap (absence of judgment in edge cases)
+
+4. **Authority Gradient Concept**: Proposes dynamic human involvement spectrum rather than binary human/machine control - from Instructional to Consultative to Supervisory to Exploratory modes.
+
+5. **Organizational Transformation Required**: Not just technical change but "choreographic maturity models" with 4 levels from Tool Usage to Organizational Intelligence.
+
+6. **Open Research Questions Explicitly Stated**:
+   - How to maintain human agency while leveraging agent efficiency?
+   - What are limits of organizational intelligence?
+   - How to ensure alignment with human values as systems become more autonomous?
+
+### Relevant Quotes/Sections Found
+
+> "Pure automation assumes complete knowledge of the problem space. It requires that all possible states, transitions, and edge cases be enumerable at design time."
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, The Brittleness of Complete Systems
+
+> "At its heart, Amorphic solves the **handoff problem** - the friction that occurs when moving between human creative processes and systematic execution."
+> Source: docs.amorphic/01-EXECUTIVE_SUMMARY.md, The Core Innovation
+
+> "Context collapse occurs at the moment when predetermined logic meets unpredictable reality, and the system has no mechanism for negotiation, no capacity for doubt, no way to ask 'what should I do here?'"
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, The Context Collapse
+
+> "The result is brittle automation that works beautifully until it doesn't - systems that handle 80% of cases flawlessly but create chaos in the remaining 20%."
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, The Judgment Gap
+
+> "Organizations begin tracking metrics like intervention precision (how often human oversight improves outcomes), learning velocity (how quickly human-AI teams adapt to new challenges), and decision architecture resilience"
+> Source: docs.amorphic/06-ORGANIZATIONAL_TRANSFORMATION.md, Measuring Success in Hybrid Organizations
+
+> "How do we ensure HumanWork organizations remain aligned with human values as they become more autonomous? What are the limits of organizational intelligence?"
+> Source: docs.amorphic/08-FUTURE_IMPLICATIONS_AND_RESEARCH_DIRECTIONS.md, Open Questions
+
+### Themes Identified
+
+1. **Choreography over Automation**: The docs consistently push "choreography" metaphor - dynamic coordination vs rigid orchestration
+
+2. **Human Judgment is Irreplaceable**: Edge cases, exceptions, and contextual judgment cannot be automated - this is a feature not a bug
+
+3. **Trust Through Transparency**: Event-driven architecture enabling radical transparency and intervention at any point
+
+4. **Memory as Active Participant**: Memory isn't just storage but "connective tissue" and "geometric imprints" that participate in reasoning
+
+5. **Gradual Authority Shift**: Organizations should expand AI autonomy as confidence builds, not grant it upfront
+
+6. **Network Effects of Collaboration**: Choreographic maturity creates ecosystem-level advantages when organizations work together
+
+7. **Perverse Incentives**: Current automation creates incentives to avoid innovative approaches because they're "automation-incompatible"
+
+## Tool Evaluation
+
+### What Worked Well
+
+- `mdcontext context` command is excellent - 44-61% token reduction while preserving key content
+- `mdcontext tree` for document outlines is helpful for understanding structure
+- `mdcontext search` works well for keyword-based exploration
+- Token counts shown everywhere help with context budgeting
+- Stats command gives good overview of indexed content
+- Multiple output formats supported (normal, JSON, pretty JSON)
+
+### What Was Frustrating
+
+- Search doesn't work with path argument like `mdcontext search "term" docs.amorphic/` - always says "No index found" even though index exists
+- The `_0.BLURB.md` context returned essentially nothing (100% reduction to 57 tokens from 2449) - unclear why
+- No way to filter search results to specific directories/paths after indexing
+- Index command prompts for semantic search confirmation which blocks in non-interactive use
+- Search results return max 10 items with no pagination option visible
+- Cannot search for multiple terms without boolean operators (AND/OR)
+
+### What Was Missing
+
+- **Directory-scoped search**: Critical for multi-folder repos. Having to search the whole index then mentally filter is inefficient
+- **Semantic search without embeddings**: The tool prompts for OpenAI API but doesn't make it easy to do without
+- **Context for multiple files at once**: Would love `mdcontext context docs.amorphic/*.md -t 10000`
+- **Search result limits/pagination**: Hard to know if I'm missing relevant results
+- **Fuzzy/stemmed search**: Searching "suggest" doesn't find "suggestion" - need exact terms
+- **Negative filtering**: Can't easily exclude certain directories or patterns
+- **Section-level context extraction**: Can get file context but not section-specific context easily
+
+### Confidence Level
+
+[X] Medium
+
+The tool helped me find key themes and quotes faster than reading all ~62K tokens of docs.amorphic/ content. However, I'm uncertain whether the keyword search missed important feedback that used different terminology. The inability to scope searches to the target directory was a significant limitation. The context summaries were very useful but varied in quality (the blurb file got reduced to nothing).
+
+### Would Use Again? (1-5)
+
+[4] - Good for quick exploration and context extraction. The `context` command alone is valuable. Search limitations are frustrating but workable with creative query strategies. Would be a 5 with directory-scoped search.
+
+## Time & Efficiency
+
+- Commands run: 38 (including retries and experiments)
+- Productive commands: ~25
+- Compared to reading all files: **Much less time** - docs.amorphic/ is ~62K tokens; I got useful summaries from ~8K tokens of context output plus search results
+- Estimated time saved: Would take 20-30 min to read all docs.amorphic/ files; tool exploration took ~10-15 min equivalent

package/research/dogfood/strategy-a/a3-llm.md

@@ -0,0 +1,164 @@
+# Report: A3 - LLM Chat Analyst
+
+## Mission
+
+Extract additional feedback and ideas from docs.llm/ (ignoring vector7/)
+
+## Command Log
+
+| #   | Command                                                                 | Purpose                | Result                                           | Useful?     |
+| --- | ----------------------------------------------------------------------- | ---------------------- | ------------------------------------------------ | ----------- |
+| 1   | `mdcontext --help`                                                      | Learn tool             | Showed commands, options, examples               | Yes         |
+| 2   | `mdcontext tree docs.llm/`                                              | List all files         | Found 3 files: amorphic.md, feedback.md, spec.md | Yes         |
+| 3   | `mdcontext index docs.llm/ --force`                                     | Index directory        | Ran in background                                | Yes         |
+| 4   | `mdcontext stats docs.llm/`                                             | Check index stats      | 3 docs, 89K tokens, 448 sections                 | Very useful |
+| 5   | `mdcontext tree docs.llm/feedback.md`                                   | Show outline           | Revealed section structure (11K tokens)          | Yes         |
+| 6   | `mdcontext tree docs.llm/amorphic.md`                                   | Show outline           | Revealed section structure (21K tokens)          | Yes         |
+| 7   | `mdcontext tree docs.llm/spec.md`                                       | Show outline           | Revealed section structure (56K tokens)          | Yes         |
+| 8   | `mdcontext search "feedback" docs.llm/`                                 | Find feedback content  | 10 results with context                          | Yes         |
+| 9   | `mdcontext search "ideas" docs.llm/`                                    | Find ideas             | 6 results                                        | Moderate    |
+| 10  | `mdcontext search "suggestion OR recommend" docs.llm/`                  | Find suggestions       | 10 results                                       | Moderate    |
+| 11  | `mdcontext search "problem OR challenge OR limitation" docs.llm/`       | Find problems          | 10 results, critical themes                      | Yes         |
+| 12  | `mdcontext search "innovation OR future OR vision" docs.llm/`           | Find future vision     | 10 results                                       | Yes         |
+| 13  | `mdcontext search "improve OR enhancement OR better" docs.llm/`         | Find improvements      | 10 results                                       | Yes         |
+| 14  | `mdcontext context docs.llm/feedback.md -t 3000`                        | Summarize feedback.md  | Got condensed overview (16% of file)             | Yes         |
+| 15  | `mdcontext context docs.llm/amorphic.md --section "Research Frontiers"` | Get research section   | Clean targeted content                           | Very useful |
+| 16  | `mdcontext context docs.llm/amorphic.md --section "Open Questions"`     | Get open questions     | 3 key questions                                  | Very useful |
+| 17  | `mdcontext search "trust OR security OR privacy"`                       | Find trust themes      | 10 results                                       | Yes         |
+| 18  | `mdcontext context docs.llm/feedback.md --section "The Core Thesis"`    | Get core thesis        | Key product vision                               | Very useful |
+| 19  | `mdcontext search "agent OR autonomous OR automation"`                  | Find automation themes | 10 results, deep content                         | Yes         |
+| 20  | `mdcontext context ... --section "The Paradox of Automation"`           | Get paradox section    | Insightful content                               | Very useful |
+| 21  | `mdcontext context ... --section "From Platform to Paradigm"`           | Get paradigm section   | Rich philosophical content                       | Very useful |
+| 22  | `mdcontext search "workflow OR process OR pattern"`                     | Find workflow themes   | 10 results                                       | Yes         |
+| 23  | `mdcontext context ... --section "What Problem This Solves"`            | Get problem statement  | Clear product definition                         | Very useful |
+| 24  | `mdcontext context ... --section "Key Differentiators"`                 | Get differentiators    | Comparison table                                 | Yes         |
+| 25  | `mdcontext search "memory OR knowledge OR context"`                     | Find memory themes     | 10 results                                       | Yes         |
+| 26  | `mdcontext context ... --section "Geometric Memory Architecture"`       | Get memory arch        | Core innovation                                  | Very useful |
+| 27  | `mdcontext context ... --section "Anti-Patterns"`                       | Get anti-patterns      | Clear guardrails                                 | Yes         |
+| 28  | `mdcontext search "user OR experience OR usability"`                    | Find UX themes         | 10 results                                       | Moderate    |
+| 29  | `mdcontext context ... --section "The Authority Gradient"`              | Get authority section  | Key innovation                                   | Very useful |
+| 30  | `mdcontext search "scale OR enterprise OR organization"`                | Find scale themes      | 10 results                                       | Moderate    |
+| 31  | `mdcontext context ... --section "Philosophy"`                          | Get philosophy         | Core principles                                  | Yes         |
+| 32  | `mdcontext context ... --section "Designing for Emergence"`             | Get emergence section  | Design principles                                | Very useful |
+
+## Findings
+
+### Key Discoveries
+
+1. **docs.llm/ contains LLM-generated product vision documents** - These are AI-written explorations of a "HumanWork" (also called "Amorphic") platform for human-AI collaboration orchestration.
+
+2. **Core Product Vision: "Operating System for Work"** - The documents describe a system that bridges human creativity with AI execution, using immutable event ledgers and role-based abstractions.
+
+3. **Three-Layer Memory Architecture** - Event (immutable facts), Status (derived views), Semantic (AI-assisted understanding) - a sophisticated memory model for persistent AI collaboration.
+
+4. **Explicit Anti-Automation Stance** - The documents articulate why pure automation fails for knowledge work and propose "choreography" as an alternative paradigm.
+
+5. **Research-Grade Thinking** - Includes open questions, research frontiers, and mature consideration of organizational transformation.
+
+### Relevant Quotes/Sections Found
+
+> "Enterprise adoption of autonomous agents has stalled due to **Opacity** (we don't know how the agent works) and **Risk** (we can't trust it to run unsupervised)."
+> Source: feedback.md, "The Core Thesis"
+
+> "In order for AI to automate humans, we must first orchestrate humans. HumanWork is that orchestration layer."
+> Source: feedback.md, "The Core Thesis"
+
+> "The most sophisticated choreographed intelligence systems often appear less automated than simpler ones."
+> Source: amorphic.md, "The Paradox of Automation"
+
+> "How do we ensure HumanWork organizations remain aligned with human values as they become more autonomous?"
+> Source: amorphic.md, "Open Questions"
+
+> "Memory is not: Chat logs, Raw execution logs, Agent recall, Hidden embeddings. Memory is: Immutable facts, Derived views, Shared context, Inspectable truth."
+> Source: spec.md, "Memory Philosophy"
+
+> "The system helps humans think better - it never decides for them."
+> Source: spec.md, "Philosophy"
+
+> "What emerges isn't just a more capable system - it's a new category of intelligence entirely."
+> Source: feedback.md, "From Platform to Paradigm"
+
+### Themes Identified
+
+1. **Human-AI Choreography** - Reframing "automation" as "collaboration" with explicit authority gradients and intervention points
+
+2. **Memory as Infrastructure** - Treating organizational memory as first-class infrastructure with event sourcing and immutable ledgers
+
+3. **Trust Through Transparency** - Building trust via observable behavior rather than assumed reliability
+
+4. **Emergent Intelligence** - Designing systems that grow and learn rather than being fully specified upfront
+
+5. **Anti-Patterns as Guardrails** - Explicit documentation of what NOT to do (e.g., never hide events, never let workflows execute directly)
+
+6. **Workspace Metaphor** - Cognitive workspaces that maintain context across sessions and enable parallel exploration
+
+7. **Role Abstraction** - Separating the "what" of work from "who does it" (human vs AI actor)
+
+8. **Recursive Improvement** - Meta-learning where the collaboration system itself improves at collaboration
+
+## Tool Evaluation
+
+### What Worked Well
+
+- **Section-targeted context** (`--section` flag) was extremely effective for extracting specific topics from large files
+- **Boolean search operators** (OR, AND) enabled comprehensive theme discovery
+- **Tree command with outlines** provided excellent navigation for 56K+ token documents
+- **Token budget controls** (`-t` flag) allowed reasonable context extraction
+- **Search with line context** showed surrounding text, making results interpretable
+- **Stats command** gave immediate understanding of corpus size and complexity
+
+### What Was Frustrating
+
+- **No embeddings by default** - Every search reminded me to run `--embed` but I stayed with keyword search
+- **10 result limit** on searches - Could not see full scope of matches without multiple queries
+- **Boolean search required explicit operators** - Had to use "OR" not natural language
+- **Context command truncation** - The 16% of feedback.md felt limiting for a summary
+- **No way to exclude sections** - Could not say "give me everything EXCEPT this section"
+
+### What Was Missing
+
+- **Cross-file semantic search** - Would have been useful to find themes across all 3 files at once
+- **Relevance ranking** - Results came in document order, not relevance order
+- **Summary generation** - Would appreciate AI-generated summaries of search results
+- **Export to structured format** - No easy way to extract findings programmatically
+- **Highlight/annotation** - Cannot mark sections for later reference
+
+### Confidence Level
+
+[X] High - The tool gave me reliable, reproducible access to the content. Boolean searches and section targeting let me systematically explore 89K tokens of dense material.
+
+### Would Use Again? (1-5)
+
+**4** - Strong tool for navigating large markdown corpora. The section-targeting feature is genuinely valuable for long documents. Would score 5 if semantic search was enabled by default and result limits were configurable. The approach of "tree to understand structure, search to find content, context to extract" is a solid workflow.
+
+## Time & Efficiency
+
+- Commands run: 32
+- Compared to reading all files: **Much less** - 89K tokens would take significant time to read raw. The tool allowed surgical extraction of relevant content in under 15 minutes of exploration.
+
+## Additional Observations
+
+### These are High-Quality Design Documents
+
+The docs.llm/ folder contains what appears to be Claude-generated (or Claude-assisted) exploration of a complex product vision. The thinking is sophisticated, covering:
+
+- Architectural patterns
+- Organizational transformation
+- Research frontiers
+- Anti-patterns and guardrails
+- Philosophy and design principles
+
+### Feedback for the Product (HumanWork/Amorphic)
+
+From the content I extracted, the documents themselves surface several self-reflective questions:
+
+1. How to prevent "organizational capture" where systems optimize for self-perpetuation
+2. How to maintain human agency while leveraging AI efficiency
+3. How to ensure value alignment as systems become more autonomous
+4. How to measure success in "hybrid organizations"
+
+These open questions represent mature product thinking and should inform roadmap priorities.
+
+### The "Memory Is All You Need" Parallel
+
+The feedback.md document draws an explicit parallel between the Transformer "Attention Is All You Need" breakthrough and their proposed "Memory Is All You Need" architecture. This is a bold positioning that frames the product as a paradigm shift rather than incremental improvement.