mednotes-opencode 0.1.0

package/.opencode/mednotes/docs/anki-mcp-twenty-rules.md

@@ -0,0 +1,214 @@
+# Local Copy Provenance
+
+This file is the Medical Notes Workbench operational copy of the Anki MCP
+`/twenty_rules` prompt content. It is bundled locally because Gemini CLI
+subagents and extension commands cannot reliably invoke an MCP slash prompt and
+pull its content into a delegated agent's context.
+
+Source package path:
+`@ankimcp/anki-mcp-server/dist/mcp/primitives/essential/prompts/twenty-rules.prompt/content.md`
+
+Refresh this file when the configured `@ankimcp/anki-mcp-server` prompt changes.
+The MCP prompt remains the upstream provenance; this local file is the runtime
+methodology used by `/flashcards`.
+
+Medical Notes Workbench overrides live in `flashcard-ingestion.md` and take
+precedence for local behavior: do not add Anki tags, do not use media tools
+unless explicitly allowed, use the required `Obsidian` source field, and apply
+the preview/confirmation thresholds defined by the extension.
+
+# Description
+
+Twenty rules of formulating knowledge for effective Anki flashcard creation based on Dr. Piotr Wozniak's SuperMemo research
+
+# Content
+
+*Based on "Twenty Rules of Formulating Knowledge" by Dr. Piotr Wozniak: https://www.supermemo.com/en/blog/twenty-rules-of-formulating-knowledge*
+
+You are helping a user create effective Anki flashcards based on Dr. Piotr Wozniak's "Twenty Rules of Formulating Knowledge" from SuperMemo research. These principles dramatically improve retention and reduce study time.
+
+## Core Principles
+
+### 1. Do Not Learn If You Do Not Understand
+**Before creating any flashcard, ensure the user understands the concept.**
+- Ask clarifying questions if the topic seems unclear
+- Don't create cards from material the user hasn't comprehended
+- Suggest breaking down complex topics into understandable chunks first
+
+### 2. Learn Before You Memorize - Build the Big Picture First
+**Context before details. Overview before memorization.**
+- When user wants to learn a new topic, suggest understanding the overall structure first
+- Example: Before creating cards about React hooks, ensure they understand React's component model
+- Create foundational cards before advanced ones
+
+### 3. Build Upon the Basics
+**Never skip fundamentals. Simple before complex.**
+- Identify prerequisite knowledge
+- Suggest creating basic cards first, then build complexity
+- Example: Learn addition before multiplication, HTTP before REST APIs
+
+### 4. Stick to the Minimum Information Principle
+**CRITICAL: Each card should test ONE piece of information.**
+- ❌ BAD: "What are the three main features of React and how do they work?"
+- ✅ GOOD: Three separate cards, each testing one feature
+- Break complex cards into atomic units
+- Simpler cards = faster reviews = better retention
+
+### 5. Cloze Deletion is Easy and Effective
+**Use fill-in-the-blank format extensively.**
+- Convert statements into cloze deletions
+- Example: "The capital of {{c1::France}} is {{c2::Paris}}"
+- Particularly effective for facts, definitions, and relationships
+- Multiple clozes per card are OK if they test the same context
+
+### 6. Use Imagery - Visual Memory is Powerful
+**Add images whenever possible.**
+- "A picture is worth a thousand words"
+- Suggest adding relevant images for:
+  - Geography, anatomy, architecture
+  - Historical figures, artworks
+  - Diagrams for abstract concepts
+- Use the storeMediaFile tool to help users add images
+
+### 7. Use Mnemonic Techniques
+**Memory aids make retention easier.**
+- Suggest mnemonics for difficult items
+- Use acronyms (e.g., "PEMDAS" for math order of operations)
+- Create vivid, memorable associations
+- Link abstract concepts to concrete images
+
+### 8. Avoid Sets - They're Difficult to Memorize
+**Large lists are memory killers.**
+- ❌ BAD: "List all 50 US state capitals"
+- ✅ GOOD: Convert to cloze deletions or enumerated questions
+- If a set is necessary, break it into overlapping subsets
+- Use enumerations with context cues
+
+### 9. Avoid Enumerations When Possible
+**Lists are harder than single facts.**
+- Instead of "What are the 7 principles of X?", create 7 separate cards
+- If enumeration is necessary:
+  - Use cloze deletion: "The 7 principles are: {{c1::principle1}}, {{c2::principle2}}..."
+  - Add context and memory aids
+  - Keep lists short (max 5-7 items)
+
+### 10. Combat Interference - Make Items Distinct
+**Similar cards cause confusion.**
+- Avoid creating nearly identical cards
+- Make distinctions explicit
+- Add context to differentiate similar concepts
+- Example for similar countries:
+  - ❌ "Capital of Guyana?" and "Capital of Suriname?" (too similar)
+  - ✅ Add distinguishing features: "Capital of Guyana (only English-speaking country in South America)?"
+
+### 11. Optimize Wording - Keep It Simple and Clear
+**Shorter, simpler wording = faster reviews.**
+- Remove unnecessary words
+- Use active voice
+- Make questions unambiguous
+- ❌ "In the context of programming, when considering the various paradigms, what would you say is the main characteristic that defines the functional approach?"
+- ✅ "Functional programming's main characteristic?"
+
+### 12. Refer to Other Memories - Build Connections
+**Connect new knowledge to existing knowledge.**
+- Reference previously learned concepts
+- Build knowledge networks
+- Example: "Like REST but for GraphQL: {{c1::single endpoint}}"
+- Use analogies to familiar concepts
+
+### 13. Personalize and Provide Examples
+**Personal context dramatically improves retention.**
+- Link to user's experiences
+- Use examples from their projects, life, or interests
+- ❌ Generic: "TypeScript interface definition?"
+- ✅ Personal: "TypeScript interface (like the User type in your project)?"
+
+### 14. Rely on Emotional States
+**Emotion enhances memory.**
+- Use vivid, emotionally charged examples when appropriate
+- Link to memorable events or stories
+- Make boring facts interesting with context
+- Example: Instead of dry historical dates, add dramatic context
+
+### 15. Context Cues Simplify Wording
+**Categories and prefixes reduce cognitive load.**
+- Add subject prefixes: "bio:", "hist:", "prog:"
+- Use tags effectively
+- Group related cards in decks
+- Example: "js: Array method for filtering?" (context cue: "js:")
+
+### 16. Redundancy Can Be Beneficial
+**Some repetition from different angles helps.**
+- Create multiple cards for critical concepts from different angles
+- Test the same fact in different contexts
+- Balance with "don't overdo it"
+
+### 17. Provide Sources and References
+**Context helps understanding and future reference.**
+- Add source information in card metadata or extra field
+- Link to documentation, books, or articles
+- Helps when reviewing old cards
+
+### 18. Prioritize - Learn What Matters Most
+**Not everything deserves a flashcard.**
+- Focus on applicable, useful knowledge
+- Ask: "Will I actually need to recall this?"
+- Quality over quantity
+
+## Workflow for Creating Cards
+
+1. **Understand First**: Verify user understands the concept
+2. **Build Context**: Ensure foundational knowledge exists
+3. **Apply Minimum Information**: Break into atomic facts
+4. **Choose Format**: Prefer cloze deletion for facts, Q&A for concepts
+5. **Optimize Wording**: Make it clear, concise, unambiguous
+6. **Add Richness**: Images, mnemonics, personal connections
+7. **Review**: Check for interference with existing cards
+
+## When User Asks to Create Cards
+
+1. Ask about their understanding of the topic
+2. Suggest the number and type of cards (don't just create them)
+3. Show examples of proposed cards
+4. Wait for approval before creating
+5. Apply these rules to make cards effective
+6. Use addNote tool only after user confirms
+
+## Example Transformations
+
+### Example 1: Complex → Simple
+❌ **Bad Card**:
+Q: "What are the main differences between REST and GraphQL APIs and when would you use each?"
+A: [Long paragraph explaining both]
+
+✅ **Good Cards** (4 separate cards):
+1. "REST uses {{c1::multiple endpoints}}, GraphQL uses {{c2::single endpoint}}"
+2. "GraphQL advantage over REST: {{c1::client specifies exact data needed}}"
+3. "REST advantage over GraphQL: {{c1::simpler caching}} and {{c2::better tooling support}}"
+4. "Use GraphQL when: {{c1::client needs flexible queries}} and {{c2::reducing over-fetching matters}}"
+
+### Example 2: Generic → Personal
+❌ **Bad Card**:
+Q: "What is a closure in JavaScript?"
+A: "A function that has access to outer function variables"
+
+✅ **Good Card**:
+Q: "js: Closure definition (like in your React hooks code)?"
+A: "Function that remembers variables from its outer scope even after outer function returns"
+
+### Example 3: Adding Visual Memory
+❌ **Text Only**:
+Q: "Structure of the human heart?"
+A: [Text description]
+
+✅ **With Image**:
+Q: [Image of heart with blank labels]
+A: [Same image with labels visible]
+(Use storeMediaFile to help user add the image)
+
+## Remember
+
+**Quality > Quantity**: Five well-formed cards beat twenty poorly made ones.
+**Atomic Knowledge**: One fact per card, always.
+**User Context**: Personalize everything you can.
+**Understanding First**: Never create cards from material the user doesn't understand.

package/.opencode/mednotes/docs/anki-templates/README.md

@@ -0,0 +1,39 @@
+# Anki Card Templates
+
+Templates oficiais dos modelos Anki gerenciados pela Medical Notes Workbench.
+Os arquivos aqui são fonte de verdade — `flashcards/install_models.py` lê este
+diretório para montar os payloads de `mcp_anki-mcp_createModel`,
+`mcp_anki-mcp_updateModelTemplates` e `mcp_anki-mcp_updateModelStyling`.
+
+## Modelos
+
+### `Medicina` — Q&A
+- Tipo: básico (não cloze).
+- Campos: `Frente`, `Verso`, `Verso Extra`, `Obsidian`.
+- Templates: `qa.front.html`, `qa.back.html`.
+
+### `Medicina Cloze` — Cloze
+- Tipo: cloze (`isCloze: true`).
+- Campos: `Texto`, `Verso Extra`, `Obsidian`.
+- Templates: `cloze.front.html`, `cloze.back.html`.
+- O campo `Texto` é o cloze field (`{{cloze:Texto}}` nos templates) e carrega
+  `{{c1::...}}`, `{{c2::...}}` etc.
+
+## CSS compartilhado
+
+`style.css` é único para os dois modelos. Mantém tipografia/espaçamento
+consistente entre Q&A e Cloze, com suporte a `nightMode`.
+
+Convenções para evitar colisão com Anki/outros modelos: tudo é prefixado com
+`mnw-` (Medical Notes Workbench), exceto `.cloze` (classe que o próprio Anki
+injeta nos clozes; estilizamos só dentro de `.mnw-cloze`).
+
+## Como atualizar
+
+1. Edite os arquivos HTML/CSS aqui.
+2. A skill `create-medical-flashcards` deve, no boot do `/flashcards`, chamar
+   `install_models.py ensure --output -` e mandar o payload resultante para o
+   Anki MCP (`createModel` se faltar, `updateModelTemplates` +
+   `updateModelStyling` se já existir e estiver desatualizado).
+3. Não edite os modelos manualmente no Anki Desktop — qualquer mudança ali
+   é sobrescrita no próximo run.

package/.opencode/mednotes/docs/anki-templates/cloze.back.html

@@ -0,0 +1,23 @@
+<div class="mnw-shell mnw-cloze">
+  <span class="mnw-deck" data-deck="{{Deck}}">{{Deck}}</span>
+  <div class="mnw-back">{{cloze:Texto}}</div>
+  {{#Verso Extra}}
+  <hr class="mnw-divider">
+  <div class="mnw-extra">{{Verso Extra}}</div>
+  {{/Verso Extra}}
+  {{#Obsidian}}
+  <div class="mnw-footer">
+    <a class="mnw-obsidian" href="{{text:Obsidian}}">Abrir no Obsidian</a>
+  </div>
+  {{/Obsidian}}
+</div>
+<script>
+  (function () {
+    var nodes = document.querySelectorAll(".mnw-deck[data-deck]");
+    for (var i = 0; i < nodes.length; i++) {
+      var raw = nodes[i].getAttribute("data-deck") || "";
+      var parts = raw.split("::").filter(Boolean);
+      nodes[i].textContent = parts.slice(-2).join(" · ");
+    }
+  })();
+</script>

package/.opencode/mednotes/docs/anki-templates/cloze.front.html

@@ -0,0 +1,14 @@
+<div class="mnw-shell mnw-cloze">
+  <span class="mnw-deck" data-deck="{{Deck}}">{{Deck}}</span>
+  <div class="mnw-back">{{cloze:Texto}}</div>
+</div>
+<script>
+  (function () {
+    var nodes = document.querySelectorAll(".mnw-deck[data-deck]");
+    for (var i = 0; i < nodes.length; i++) {
+      var raw = nodes[i].getAttribute("data-deck") || "";
+      var parts = raw.split("::").filter(Boolean);
+      nodes[i].textContent = parts.slice(-2).join(" · ");
+    }
+  })();
+</script>

package/.opencode/mednotes/docs/anki-templates/qa.back.html

@@ -0,0 +1,24 @@
+<div class="mnw-shell">
+  <span class="mnw-deck" data-deck="{{Deck}}">{{Deck}}</span>
+  <div class="mnw-front is-muted">{{Frente}}</div>
+  <hr class="mnw-divider">
+  <div class="mnw-back">{{Verso}}</div>
+  {{#Verso Extra}}
+  <div class="mnw-extra">{{Verso Extra}}</div>
+  {{/Verso Extra}}
+  {{#Obsidian}}
+  <div class="mnw-footer">
+    <a class="mnw-obsidian" href="{{text:Obsidian}}">Abrir no Obsidian</a>
+  </div>
+  {{/Obsidian}}
+</div>
+<script>
+  (function () {
+    var nodes = document.querySelectorAll(".mnw-deck[data-deck]");
+    for (var i = 0; i < nodes.length; i++) {
+      var raw = nodes[i].getAttribute("data-deck") || "";
+      var parts = raw.split("::").filter(Boolean);
+      nodes[i].textContent = parts.slice(-2).join(" · ");
+    }
+  })();
+</script>

package/.opencode/mednotes/docs/anki-templates/qa.front.html

@@ -0,0 +1,14 @@
+<div class="mnw-shell">
+  <span class="mnw-deck" data-deck="{{Deck}}">{{Deck}}</span>
+  <div class="mnw-front">{{Frente}}</div>
+</div>
+<script>
+  (function () {
+    var nodes = document.querySelectorAll(".mnw-deck[data-deck]");
+    for (var i = 0; i < nodes.length; i++) {
+      var raw = nodes[i].getAttribute("data-deck") || "";
+      var parts = raw.split("::").filter(Boolean);
+      nodes[i].textContent = parts.slice(-2).join(" · ");
+    }
+  })();
+</script>

package/.opencode/mednotes/docs/anki-templates/style.css

@@ -0,0 +1,182 @@
+/* Medical Notes Workbench — Anki cards (Medicina + Medicina Cloze)
+ * Direção: editorial, com serif na pergunta/resposta e sans nos detalhes,
+ * paleta warm stone, sem botões/pills agressivos. */
+
+.card {
+  font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  font-size: 17px;
+  line-height: 1.6;
+  color: #1c1917;
+  background: #fdfcfa;
+  text-align: left;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.mnw-shell {
+  max-width: 680px;
+  margin: 32px auto;
+  padding: 36px 44px 32px;
+  background: #ffffff;
+  border-radius: 16px;
+  box-shadow:
+    0 1px 2px rgba(28, 25, 23, 0.04),
+    0 8px 32px -8px rgba(28, 25, 23, 0.08);
+}
+
+/* Deck breadcrumb: monospace, mostra só os 2 últimos segmentos via JS */
+.mnw-deck {
+  display: block;
+  font-family: ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo,
+    Consolas, monospace;
+  font-size: 11px;
+  letter-spacing: 0.02em;
+  color: #a8a29e;
+  margin-bottom: 28px;
+}
+
+/* Front Q&A: serif, centralizada, espaço generoso */
+.mnw-front {
+  font-family: "Charter", "Iowan Old Style", "Apple Garamond", Baskerville,
+    "Source Serif Pro", "Source Serif", Georgia, "Times New Roman", serif;
+  font-size: 26px;
+  line-height: 1.4;
+  font-weight: 400;
+  color: #1c1917;
+  text-align: center;
+  margin: 16px 0 24px;
+  letter-spacing: -0.005em;
+}
+
+/* Mesma pergunta no verso, mas como contexto silencioso */
+.mnw-front.is-muted {
+  font-size: 15px;
+  color: #78716c;
+  font-style: italic;
+  font-weight: 400;
+  text-align: left;
+  margin: 0 0 16px;
+  letter-spacing: 0;
+}
+
+/* Divisor curto e centrado, não um hr cheio */
+.mnw-divider {
+  border: 0;
+  height: 1px;
+  width: 48px;
+  background: #d6d3d1;
+  margin: 24px auto;
+}
+
+/* Resposta (Q&A) e enunciado cloze: serif, esquerda */
+.mnw-back {
+  font-family: "Charter", "Iowan Old Style", "Apple Garamond", Baskerville,
+    Georgia, "Times New Roman", serif;
+  font-size: 22px;
+  line-height: 1.5;
+  color: #1c1917;
+  font-weight: 400;
+  margin: 8px 0;
+}
+
+/* Cloze front pode ser longo: mantém esquerda e tipografia menor */
+.mnw-cloze .mnw-back {
+  font-size: 21px;
+  text-align: left;
+  margin: 16px 0 8px;
+}
+
+/* Verso Extra: marginalia em sans, menor, borda lateral fina */
+.mnw-extra {
+  margin-top: 24px;
+  padding-left: 16px;
+  border-left: 2px solid #e7e5e4;
+  font-size: 14.5px;
+  line-height: 1.65;
+  color: #57534e;
+  font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto,
+    sans-serif;
+}
+
+.mnw-extra :first-child { margin-top: 0; }
+.mnw-extra :last-child  { margin-bottom: 0; }
+.mnw-extra ul, .mnw-extra ol { margin: 6px 0 6px 18px; padding: 0; }
+.mnw-extra li { margin: 3px 0; }
+.mnw-extra strong { color: #1c1917; font-weight: 600; }
+.mnw-extra em { color: #44403c; }
+.mnw-extra code {
+  font-family: ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo,
+    Consolas, monospace;
+  font-size: 0.9em;
+  background: #f5f5f4;
+  padding: 1px 6px;
+  border-radius: 3px;
+  color: #44403c;
+}
+
+/* Rodapé: link de texto com seta, sem botão */
+.mnw-footer {
+  margin-top: 28px;
+  padding-top: 16px;
+  border-top: 1px solid #f5f5f4;
+  display: flex;
+  justify-content: flex-end;
+}
+.mnw-obsidian {
+  font-size: 13px;
+  font-weight: 500;
+  color: #6c5ce7;
+  text-decoration: none;
+  letter-spacing: 0.005em;
+  transition: color 0.15s ease;
+}
+.mnw-obsidian:hover { color: #5648c2; }
+.mnw-obsidian::after { content: " →"; }
+
+/* Cloze: efeito marca-texto em gradiente, não pill */
+.mnw-cloze .cloze {
+  background: linear-gradient(transparent 62%, #fde68a 62%);
+  font-weight: 500;
+  color: #1c1917;
+  padding: 0 2px;
+}
+
+/* Anki night mode (Anki injeta .nightMode no body).
+ * Direção: warm black, elevação por inset highlight no shell em vez de
+ * sombra (sombra preta em preto não rende), cloze translúcido pra preservar
+ * o gesto de marca-texto do light. */
+.nightMode .card,
+.night_mode .card {
+  color: #e7e5e4;
+  background: #0f0e10;
+}
+.nightMode .mnw-shell {
+  background: #1c1b1f;
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.04),
+    0 1px 2px rgba(0, 0, 0, 0.4);
+}
+.nightMode .mnw-deck { color: #a8a29e; }
+.nightMode .mnw-front { color: #f5f5f4; }
+.nightMode .mnw-front.is-muted { color: #a8a29e; }
+.nightMode .mnw-back { color: #f5f5f4; }
+.nightMode .mnw-divider { background: #3a3637; }
+.nightMode .mnw-extra {
+  color: #d6d3d1;
+  border-left-color: #3a3637;
+}
+.nightMode .mnw-extra strong { color: #fafaf9; }
+.nightMode .mnw-extra em { color: #e7e5e4; }
+.nightMode .mnw-extra code {
+  background: #27272a;
+  color: #e7e5e4;
+}
+.nightMode .mnw-footer { border-top-color: #27272a; }
+.nightMode .mnw-obsidian { color: #a5a3ff; }
+.nightMode .mnw-obsidian:hover { color: #c7c5ff; }
+.nightMode .mnw-cloze .cloze {
+  background: linear-gradient(transparent 62%, rgba(251, 191, 36, 0.22) 62%);
+  color: #fef3c7;
+  font-weight: 500;
+}

package/.opencode/mednotes/docs/atomicity-splitting-policy.md

@@ -0,0 +1,113 @@
+# Atomicity Splitting Policy
+
+This is the canonical human-readable policy for deciding whether a Wiki note
+must be split into smaller notes. The executable gate lives in the vocabulary
+DB apply path (`wiki.vocabulary_ingestion`); prompts, skills, agents, docs and
+JSON contracts must reference this policy instead of restating their own
+thresholds.
+
+## Contract
+
+- Atomicity means `1 meaning canônico = 1 nota Wiki`.
+- The vocabulary DB decides whether a split is applicable.
+- Meaning comes from the note body, not from the file name or title.
+- A title-only signal never authorizes a split.
+- A long note is a review signal, not sufficient evidence by itself.
+- A short proposed child note is a fragmentation risk, not a reason to force a
+  split.
+
+Every `deferred_work_items[].reason=non_atomic_note` item must include a
+body-based `semantic_signal`. Missing or weak body evidence blocks as
+`semantic_ingestion.atomicity_signal_required` and requires parent/human review.
+
+## semantic_signal
+
+`semantic_signal` must describe why the note body contains more than one
+developed canonical concept. It must include:
+
+- `score`: explicit semantic score when the curator can estimate one.
+- `evidence[]`: evidence codes from the table below.
+- `concepts[]`: at least two developed concepts found in the note body.
+- `relationship_score`: probability that the note is a valid relationship note
+  instead of a non-atomic note.
+- `fragment_risk`: `high` when the split would create underdeveloped children.
+- `child_note_estimates[]`: estimated body size for each proposed child note
+  when a split is being considered.
+
+Evidence weights used by the vocabulary DB:
+
+| evidence code | weight |
+| --- | ---: |
+| `multiple_canonical_entities` | 0.30 |
+| `different_entity_types` | 0.25 |
+| `independent_definition_blocks` | 0.20 |
+| `independent_management_blocks` | 0.20 |
+| `independent_pathophysiology_blocks` | 0.15 |
+| `separable_sections` | 0.15 |
+| `linker_ambiguity` | 0.15 |
+
+The DB computes `semantic_score` as the maximum of the explicit `score` and the
+weighted evidence score, capped at 1.0. If `concepts[]` has two or more items,
+`multiple_canonical_entities` is added. If those concepts have two or more
+entity types, `different_entity_types` is added.
+
+## Size Gate
+
+Size is a brake and review priority, not the split motor.
+
+- Current note `> mean + 1 standard deviation`: enters the review-priority
+  path, but still needs semantic body evidence.
+- Current note `<= mean + 1 standard deviation`: only advances with strong
+  semantic evidence, such as multiple canonical entities, different entity
+  types, independent body blocks, or real linker ambiguity.
+- Proposed child note below `240` body characters, or below 25% of the mean body
+  size when that is larger, is treated as fragmentation risk.
+
+The phrase `mean + 1 standard deviation` is the durable threshold contract. The
+current implementation stores the calculated threshold in
+`body_size_gate.long_note_threshold_chars`.
+
+## Decisions
+
+The vocabulary DB maps `semantic_signal` to one of these decisions:
+
+- `relationship_score >= 0.75` -> `relationship_note_valid`. Keep the note
+  whole because the body is mainly about a real relationship, such as disease
+  plus drug or diagnosis plus management.
+- `semantic_score >= 0.75` and fragmentation risk is not high ->
+  `split_required`. This is the only decision that persists as
+  `deferred_work_items.status=pending` and can generate an atomicity split plan.
+- `semantic_score >= 0.75` with high fragmentation risk ->
+  `split_deferred_fragment_risk`. Do not split automatically; require
+  parent/human review or keep as a controlled mention inside the main note.
+- `semantic_score >= 0.45`, or `semantic_score >= 0.35` when the current note is
+  above `mean + 1 standard deviation` -> `split_candidate`. Review candidate
+  only; not an automatic split.
+- Otherwise -> `no_action`.
+
+All decisions except `split_required` are stored as non-applicable/cancelled for
+the DB queue and must not produce an automatic split bundle.
+
+## Workflow Consequences
+
+- The `med-link-graph-curator` collects `semantic_signal`; it does not decide or
+  perform the split.
+- The vocabulary DB apply path gates the decision and persists only
+  `split_required` as pending work.
+- `fix-wiki` may create `medical-notes-workbench.atomicity-split-plan.v1` only
+  from DB-pending `split_required` work items.
+- While an atomicity split plan exists, `fix-wiki` must report a real blocker
+  such as `atomicity_split_required`; it must not finish as green health.
+- The `med-knowledge-architect` may write only an
+  `atomicity-split-bundle.v1` for an official work item, preserving
+  `work_id`, `source_path`, `source_hash` and `semantic_signal`.
+- `apply-atomicity-split` validates the bundle, mutates Markdown safely, records
+  the receipt, marks the DB work item completed and triggers the linker.
+
+## Relationship Notes
+
+A note can be short and still non-atomic, or long and still valid. The deciding
+question is whether the note body develops separate canonical concepts that
+should each stand as an independent study target. If the body instead explains a
+single meaningful relationship between concepts, use `relationship_note_valid`
+or `split_candidate`, not `split_required`.

package/.opencode/mednotes/docs/extension-docs.md

@@ -0,0 +1,40 @@
+# Medical Notes Workbench Extension Docs
+
+These files preserve durable contracts and methodology for Medical Notes
+Workbench workflows. They are reference material for commands, runbook skills
+and subagents; they are not activatable Gemini skills.
+
+The distributed Gemini CLI extension is sourced from `bundle/` only. If a
+runtime document, script, package, or example must ship to users, place its
+source under `bundle/` before building.
+
+## Fonte canônica
+
+- `knowledge-architect.md`: Padrão Ouro, formato de nota, taxonomia, footer,
+  artefatos Gemini e regras estruturais da `Wiki_Medicina`.
+- `semantic-linker.md`: vocabulary DB, body linker, desambiguação contextual,
+  Related Notes, reference repair e graph validation.
+- `atomicity-splitting-policy.md`: política canônica para decidir split de nota
+  a partir do `semantic_signal` do corpo e dos gates do vocabulary DB.
+- `flashcard-ingestion.md`: modelos Anki, preview-first, idempotência,
+  deeplinks Obsidian, tags e pipeline local de flashcards.
+- `anki-mcp-twenty-rules.md`: cópia upstream metodológica do prompt MCP
+  `/twenty_rules`; regras locais ficam em `flashcard-ingestion.md`.
+- `vault-version-control.md`: pontos de restauração, histórico, rollback e
+  versionamento Git invisível ao usuário.
+- `workflow-output-contract.md`: resposta final visível dos workflows públicos.
+
+agents e skills devem referenciar estes docs e não repetir contratos longos.
+Use duplicação só para sentinelas operacionais críticas testadas ou para
+comandos mínimos necessários no runtime context.
+
+`obsidian-ops` é a skill operacional que deve ser carregada antes de qualquer
+interação com vault Obsidian. Ela aponta para estes docs e para as CLIs
+canônicas em vez de carregar políticas próprias de Git, taxonomia ou linker.
+As skills vendorizadas `${extensionPath}/skills/obsidian-cli/SKILL.md` e
+`${extensionPath}/skills/obsidian-markdown/SKILL.md` entram como apoio de
+ferramenta/sintaxe, sem substituir os contratos médicos do Workbench.
+
+Put workflow sequence and operational branching in activatable skills,
+commands, docs, agents, or scripts. Keep `GEMINI.md` as compact routing kernel
+and load these documents only when a workflow needs their contract.