Process a journal page photo: run OCR, parse the template, extract schema
tags, store the capture, copy the image to the knowledge base, and detect
connections to existing captures.

Accept-by-default: the page is always stored. If it can't be filed
normally — no readable template ID, an ID too doubtful to trust, or a page
ID that is already taken — it is stored as a Wild Art (WA) entry with the
reason recorded, never rejected and never overwriting anything. Review
WA entries with list_by_tag(entry_type="WA") and move them to their
proper type with promote_capture().

Args:
    image_path: Absolute path to the image file (JPG, PNG, TIFF, etc.)
    force:      Set to True to REPLACE an existing capture with the same
                template ID in the same volume (default False — the new
                page is filed as WA with reason id_conflict instead).
    volume:     Which journal/book this page belongs to. 0 = automatic:
                a volume written on the page (e.g. "V2 RC-001") wins,
                otherwise the stored current_volume setting (default 1).
    wa_reason:  File the image as Wild Art on purpose. Use "loose_capture"
                for anything off-journal — a napkin sketch, sticky note,
                whiteboard, back of a receipt (no volume or page ID
                needed). Other values: manual, other.
    wa_detail:  Free-text note for a WA entry, e.g. "napkin", "whiteboard".

Returns a summary of what was found and stored, including the strongest
connection detected.

Store a journal capture from transcribed text. This is the PRIMARY path
for handwritten pages: the user shares a photo of the page, YOU (the
assistant) read it with vision, confirm the transcription with the user,
then call this tool with the text. Assistant vision is far more accurate
on handwriting than local OCR — prefer this over upload_capture whenever
the user can show you the page.

Transcribe faithfully: keep field labels (First Impressions, Key Points,
Tags, etc.) as written, include every schema tag (#topic @source !priority
?question $insight *sensory), and treat content inside tag bubbles as tags.

Accept-by-default: the capture is always stored. A template ID that
can't be parsed or found, or a page ID already taken in that volume,
files it as a Wild Art (WA) entry with the reason recorded — nothing is
rejected and nothing is overwritten.

3-D isometric grid pages have their own type: pass template_id="ISO-001"
(etc.) — transcribe the subject line, labels, and notes around the drawing.

Args:
    text:        The transcribed content of the journal page (all fields
                 you can read — First Impressions, Key Points, Tags, etc.).
    template_id: Template ID (e.g. "RC-001", "ISO-002"). If omitted, the
                 server will try to detect it from the text automatically.
                 Pass "WA" to file the capture as Wild Art by hand.
    force:       Set to True to REPLACE an existing capture with the same
                 template ID in the same volume (default False — the new
                 capture is filed as WA with reason id_conflict instead).
    volume:      Which journal/book this page belongs to. 0 = automatic:
                 a volume written on the page/text wins, otherwise the
                 stored current_volume setting (default 1).
    wa_reason:   File as Wild Art on purpose. Use "loose_capture" for
                 anything off-journal — a napkin sketch, sticky note,
                 whiteboard photo, back of a receipt (no volume or page ID
                 needed). Other values: manual, other.
    wa_detail:   Free-text note for a WA entry, e.g. "napkin", "sticky note".

Returns the same summary as upload_capture, including any connections
detected to existing captures.

Replace a stored capture's transcription with corrected text.

Use this when a capture's OCR came out wrong — for example a Tesseract
read of handwriting, or a transcription typo. The original OCR text is
preserved in the database; the corrected text becomes what search, tag
extraction, and connection detection use from now on.

Re-runs template parsing, tag extraction, and connection detection on the
corrected text.

Args:
    capture_id: The numeric capture ID (shown as #N in upload output and
                search results). Not the template ID.
    text:       The full corrected transcription of the page, including
                field labels and all schema tags.

Returns a summary of the re-parsed capture and rebuilt connections.

Assign or fix the template ID of a stored capture.

Use this for pages stored as UNIDENTIFIED (no readable template ID at
upload time) or when the ID was misread. Re-parses the stored text with
the correct template's parser and rebuilds tags and connections.

Args:
    capture_id:  The numeric capture ID (#N in upload output).
    template_id: The correct template ID, e.g. "RC-007" or "DC-003".
    volume:      Optionally move the capture to this volume (0 = keep).

Move a Wild Art (WA) entry to its proper type after review — RC, SYN,
REV, DC, or ISO (3-D isometric grid page).

The capture keeps its #id, text, image, and asserted links; it is
re-parsed as the target type. Its WA history is preserved on the
promoted entry: promoted_from (the WA-NNN ID), wa_reason, and wa_detail.

If the target page ID is already taken in that volume, NOTHING changes:
the conflict is reported and you choose — a different page ID, a
different volume (a page from a new journal), or force=True. Page IDs are
never renumbered automatically.

Args:
    capture_id:     The WA entry's numeric ID (#N).
    target_type:    RC | SYN | REV | DC | ISO.
    target_page_id: The page ID to file it under, e.g. "RC-014". Optional
                    when the page was read with an ID (claimed_page_id)
                    of the target type — that ID is used.
    volume:         Journal volume to file it in (0 = the volume the WA
                    entry already has, else the current writing volume).
    force:          DANGEROUS. Take the page ID even though another
                    capture holds it. The current holder is not deleted —
                    it is moved to Wild Art itself (reason id_conflict,
                    conflicts_with pointing here) — but every @reference
                    to that page ID from now on resolves to THIS capture.
                    Only use it when you are sure the current holder is
                    the misfiled one.

Configure journal volumes: which book new captures go into, and which
books are visible to search and browsing.

Volumes model multiple physical journals: volume 2 continues volume 1's
knowledge base (cross-volume connections are normal and expected). Set
current_volume once when starting a new book.

Args:
    current_volume: Volume for NEW captures (0 = leave unchanged).
    active_volumes: Read scope for search/list/connections tools:
                    "*" for all volumes, or a comma list like "2,3".
                    Empty = leave unchanged. journal_health and
                    knowledge_progress always see all volumes —
                    longitudinal KPIs over a truncated history would
                    mislead.

Call with no arguments to just see the current settings.

Manually link a named entity (person, place, work, organization, dream
symbol...) to a capture.

Entities are first-class objects: '@' tags that aren't template IDs
create them automatically (e.g. @Veronica, @the-old-house), and this
tool covers what extraction missed or mis-typed. Entities are global
across volumes — a character in book 1 and book 3 is one entity.

Args:
    capture_id: The capture the entity appears in.
    name:       The entity's name as written (display form).
    kind:       person | place | work | org | symbol | other

Re-derive the entire connection graph from current tags and text.

Run this after correcting OCR text, identifying previously-unidentified
pages, or uploading pages out of order — a page that referenced @RC-015
before RC-015 existed gets its edge on rebuild. Idempotent: running it
twice produces the same graph.

Assert a typed, directional relationship between two captures by hand.

Relations (source → target):
  supersedes — source replaces target. Target is closed out (kept in
               history, hidden from current-slice search — never deleted).
  refutes    — source contradicts target.
  narrows    — source restricts target's claim without overturning it.
  supports   — source is evidence for target.
  distills   — source (an AIEX distillation entry) is derived from
               target (a SYN page). Normally set automatically by
               commit_distillation(); asserting it by hand is for
               fixing or adding a link that tool didn't create.
  assesses   — source (an AIEX assessment entry) audits target (a REV
               page)'s claimed knowledge status. Normally set
               automatically by commit_assessment().
  observes   — source (an AIEX observation entry) notes target (a DC
               page)'s cross-domain echo or confirmed symbol meaning.
               Normally set automatically by commit_observation().
  develops   — source (a journal entry, e.g. a SYN page) develops the
               idea first scribbled in target (typically a loose Wild Art
               capture — a napkin sketch or sticky note). The scribble
               stays as the source; nothing is closed out.

Automatic contradiction detection is deliberately not offered — it
cannot be done reliably. Supersession is either asserted here by a
human or not recorded. Re-asserting between the same pair replaces the
previous assertion.

Args:
    source_id: The newer / asserting capture (numeric ID).
    target_id: The capture being superseded / refuted / supported / distilled / assessed / observed / developed.
    relation:  supersedes | refutes | narrows | supports | distills | assesses | observes | develops
    note:      Optional one-line reason, stored on the edge.

Find the shortest chain of connections between two captures — how one
idea reaches another through references, shared entities, asserted
relations, and strong tag overlap.

Args:
    from_id: Starting capture (numeric ID).
    to_id:   Destination capture (numeric ID).

Everything within N hops of a capture in the connection graph — its
local knowledge cluster.

Args:
    capture_id: Center capture (numeric ID).
    depth:      How many hops out to walk (default 2, max 4).

Knowledge base health check. Catches the ways a knowledge base silently
rots: orphan captures nothing links to, superseded claims not closed
out, unresolved contradictions, open questions going stale, and
fragmented tags from normalization failures.

Run it occasionally — a base that is never linted entrenches errors
instead of correcting them.

Args:
    stale_question_days: Age at which an unanswered ? question is
                         flagged (default 30).

Write the entire knowledge base to a versioned JSONL file (ksj-export-v1)
— a real backup with a matching import path, not a one-way dump.

Contains captures (all fields), tags, entities, and connections. The
format is documented in docs/EXPORT_FORMAT.md in the ksj-mcp repo, so
anything can consume it.

Args:
    file_path: Where to write. Default: ksj-export-<date>.jsonl in the
               KSJ data directory.

Restore a ksj-export-v1 JSONL backup into the knowledge base.

Additive and non-destructive: captures that collide with an existing
(volume, template ID) are skipped, nothing is overwritten. User-asserted
edges are restored; derived connections are rebuilt over the merged base.

Args:
    file_path: Path to a file produced by export_backup.

Write a self-contained HTML view of the knowledge base — a bird's-eye
browser for the whole journal that opens in any web browser, works
offline, and needs no install.

Three tabs, plus connections on every card:
  Timeline    — every capture chronologically, with live search and
                type / Wild Art reason / volume / journal-vs-AI filters
                (WA and ISO are always in the type filter); superseded
                captures hidden behind a toggle. Each card lists its
                typed connections — click one to jump to that capture.
                Wild Art cards show their reason, the page ID they were
                read as, and a link to the capture they conflict with.
  Index       — tags grouped by meaning (topics, dream themes, open
                questions, insights, motifs, sensory details) plus the
                entity register; every entry click-filters the timeline.
  Graph       — an ego-centric local graph (no rotating globe, no
                physics). The landing view groups captures into bubbles
                by tag, theme, or entity (size = capture count). Click a
                bubble, or "view in graph" on any card, to drill into a
                fixed radial layout: the item centered, its direct
                connections (or a cluster's members) around it. Click a
                neighbor to recenter; "+N more" expands a busy ring.

Navigation: every view change is a browser history step mirrored in the
URL hash, so the in-app "← Back" button AND the browser's Back button
step back through views inside the page (the browser's leaves the page
only from the first view), and reloading reopens the same view.

The footer records the ksj-mcp, mcp, pydantic, and Python versions, the
export time, and capture / entity / connection counts.

All data is inlined in the file: sharing or archiving the file shares a
snapshot of the knowledge base.

Args:
    file_path: Where to write. Default (recommended, and required on
               Windows): leave empty — writes ksj-view.html in the KSJ
               data directory.

Process all journal page photos in a folder at once.

Finds every image file (JPG, PNG, TIFF, BMP, WebP) in the folder and runs
the full upload pipeline on each one. Non-image files are skipped silently.
Accept-by-default: no page is skipped. Pages without a readable template
ID, or whose page ID is already taken, are stored as Wild Art (WA)
entries with the reason recorded — review them afterwards with
list_by_tag(entry_type="WA") and promote_capture(). Pass volume=N when
importing a second (or later) journal.

Note: by default this path uses local Tesseract OCR, which performs
poorly on cursive handwriting. For a handful of pages, share photos in
chat and store them via manual_capture instead. For large handwritten
imports, the user can enable cloud OCR with their own key
(KSJ_OCR_BACKEND=azure — see README); it is off by default and every
run states when it is active.

Args:
    folder_path: Absolute path to the folder containing journal photos.
    force:       Set to True to REPLACE existing captures with matching
                 template IDs (default False — the new page is filed as
                 WA with reason id_conflict; the existing one is untouched).

Returns a summary table of all processed images.

Search all journal entries by concept, keyword, or phrase — across every
template type (RC, SYN, REV, DC, ISO, WA, AIEX) at once.

This is the primary way to find entries by idea rather than tag. Use it
whenever the user asks to find notes, recall something they wrote, or
explore a topic. Natural language queries work well.

Examples:
  "neural networks"        → entries mentioning neural networks
  "why does attention"     → entries with that question or phrase
  "spaced repetition"      → concept search across all templates
  "dream flying"           → DC entries with flying imagery

Args:
    query:      The concept, keyword, or phrase to search for.
    tag_filter: Optional tag value to narrow results (e.g. "machine-learning").
    date_from:  Optional ISO date lower bound (e.g. "2025-09-01").
    date_to:    Optional ISO date upper bound (e.g. "2025-12-31").
    entry_type: Optional type filter: RC, SYN, REV, DC, ISO, WA, AIEX.
    wa_reason:  Optional Wild Art reason filter (id_conflict,
                unrecognized_template, ocr_low_confidence,
                validation_error, loose_capture, manual, other).

Note: search matches terms that appear in the journal text. For tag-only
browsing without a text query, use list_by_tag instead.

Show connections for a capture: @-references first (deliberate
assertions, both directions), then tag overlap ranked by IDF-weighted
strength — shared rare tags count for much more than shared common ones.

Args:
    capture_id:   The numeric ID returned by upload_capture or search_captures.
    min_strength: Minimum strength for tag-overlap edges (default 2.0 ≈
                  two ordinary shared tags or one rare one). References
                  are always shown. Lower it to see weaker links.
    limit:        Maximum connections listed (default 20). The total is
                  always reported.

Return an overview of your knowledge base: capture counts, top tags,
open questions, key insights, and date range.

Export all captures (or a tag-filtered subset) as Markdown or JSON.

Args:
    format:     "markdown" (default) or "json"
    tag_filter: Optional tag value — only include captures with this tag
                (e.g. "machine-learning")

Returns the full export as a string (no file is written).

Scan your Rapid Capture entries and identify topic clusters ready to be
synthesized into a SYN page.

Args:
    min_captures: Minimum number of RC entries on a topic to flag it
                  (default 3).

Independently scan the Rapid Capture cluster behind a Synthesis page you
have ALREADY written and photographed, then prepare a structured
dialogue comparing what the scan found against what the page found.

This runs AFTER a SYN page exists for the cluster — never before.
Running it before the page is written would let the AI perform the
cognitive act synthesis is meant to force (see
ksj2_documents/SYN_companion_decision_optionB_2026-08-03.md). There is
no override flag for this precondition — if no SYN page is found, the
tool declines and points to suggest_synthesis() instead.

The scan itself never reads the SYN page's own content before producing
its connection map, so the Phase 2 comparison is meaningful rather than
confirmatory. This tool does NOT write to the database — it prepares
the scan data and dialogue instructions for Claude to run in this
conversation. Call `commit_distillation()` after the user approves the
dialogue's outcome, to persist it.

Trigger phrases: "Run surface_connections on SYN-004", "Compare my
synthesis against an independent scan".

Args:
    syn_template_id: The SYN page's template ID (e.g. "SYN-004").
                     Required — the tool declines if no SYN page with
                     this ID exists.
    entry_ids:       Optional comma-separated RC template IDs (e.g.
                     "RC-001,RC-047,RC-083") to scan explicitly.
                     Required when the SYN page's RC cluster can't be
                     resolved automatically — no matching tag cluster,
                     or more than one candidate cluster.
    days:            Optional — narrow the resolved cluster to RC
                     entries created in the last N days. 0 = no filter.
    depth:           "brief" | "standard" (default) | "deep" — how many
                     follow-up questions per tier to plan for in the
                     dialogue. The user can also say "more on this one"
                     for any single connection regardless of depth.

Returns the RC cluster data, gap candidates, and full scan + dialogue
instructions for Claude to execute.

Store the confirmed outcome of a surface_connections() dialogue.

Call this after the Phase 2 dialogue concludes and the user has
reviewed the revised connection map. Only the distillation — what the
comparison revealed, not the connection list or the dialogue
transcript itself — is stored as the entry's text; the four categories
are kept as supporting detail alongside it.

Never creates a SYN template ID — SYN numbers belong to physical
pages. Stores with source='ai_extract' (excluded from journal_health
KPIs, distinguishable in get_breakthroughs()/export_html()) using the
AIEX sequence, and links to the SYN page with an asserted 'distills'
edge (source: the new AIEX entry, target: the SYN page).

Args:
    distillation_json: JSON string with fields:
      syn_template_id (required) — the SYN page this distills.
      distillation     (required) — 2-5 sentences: what the comparison
                       revealed and what it means. This is the artifact.
      confirmed, retired, deferred, missed, beyond_scan — lists of
                       strings, one per connection-map entry (all
                       optional, default empty).
      tags             — optional list of "#topic"/"@source"/etc strings.
      date             — optional ISO date; defaults to today.

Returns a confirmation with the assigned AIEX ID and the distills edge.

Export your open questions as a portable study deck (tab-separated CSV).

Turns every ? question in your journal into a flashcard:
  Front — the question (from the ? tag)
  Back  — connected $ insight captures; falls back to the capture summary
  Tags  — the # topic tags on that capture

The output is a standard tab-separated CSV compatible with:
  - Anki (File → Import → Tab-separated)
  - Quizlet (Import → Tab between terms, newline between cards)
  - Obsidian, Notion, Google Sheets, or any CSV-aware tool
  - Print as a plain study sheet — no app required

Args:
    tag_filter: Optional # topic tag to limit the export
                (e.g. "machine-learning"). Leave blank for all questions.

Returns a tab-separated text block. No file is written to disk.

KPI dashboard and coaching recommendations for your journal practice.

Tracks:
  - Capture velocity (captures/week over last 4 weeks)
  - Insight velocity ($ insights/week)
  - Days since last Review entry
  - Unanswered open questions and their age
  - Synthesis activity (digitized SYN pages — descriptive only)
  - Template balance (which template types are unused)

All KPIs count hand-written journal captures only; AI-extracted (AIEX)
entries are excluded so they don't inflate your practice metrics.

Returns a health score and specific, actionable recommendations.

Browse all captures that carry a specific tag — no text query required.
Also browses by entry type, which is how to review the Wild Art queue.

Use this to find every note related to a topic, source, question, or insight:
  list_by_tag("machine-learning")           → all captures with that tag
  list_by_tag("machine-learning", prefix="#") → only # topic tags
  list_by_tag("RC-012", prefix="@")          → captures referencing @RC-012
  list_by_tag("deadline", prefix="!")        → priority items
  list_by_tag("falling", role="motif")       → DC recurring motifs only
  list_by_tag(entry_type="WA")               → every unresolved Wild Art entry
  list_by_tag(entry_type="WA", wa_reason="id_conflict") → page-ID conflicts
  list_by_tag(entry_type="WA", wa_reason="loose_capture") → napkins, sticky notes…
  list_by_tag(entry_type="ISO")              → 3-D isometric grid pages

The same prefix character means different things on Dream Capture pages
(# theme, @ symbol, ! motif) than on RC/SYN/REV (# topic, @ reference,
! priority). Use *role* to select by meaning rather than character:
topic, theme, reference, entity, priority, motif, question, insight,
causal, sensory.

Args:
    tag:        Tag value to look up (without the prefix character).
                May be empty when entry_type or wa_reason is given.
    prefix:     Optional prefix character: #  @  !  ?  $  *  ->
    role:       Optional semantic role — the precise way to disambiguate
                DC vs RC/SYN/REV meanings.
    entry_type: Optional type filter: RC, SYN, REV, DC, ISO, WA, AIEX.
    wa_reason:  Optional Wild Art reason: id_conflict,
                unrecognized_template, ocr_low_confidence,
                validation_error, loose_capture, manual, other.

Report co-occurrence between Dream Capture entries and RC/REV entries
sharing #tag, within window_days of each other. Descriptive only.

This deliberately never uses the word "correlation" in its own output
(window size is a free parameter, and with a small journal, trying a
few window widths will surface something that looks meaningful — the
same researcher-degrees-of-freedom failure mode your own experimental
methodology is built to defeat). Every result reports window_days, the
match count, and the base rate of #tag in each population, so a
coincidence and a pattern don't read the same on the page.

Args:
    tag:         The # topic/theme tag to check (e.g. "resilience").
                 Matched against DC's #theme tags and RC/REV's #topic
                 tags — same prefix, same normalized value, different
                 template role.
    window_days: How many days apart counts as "near" (default 3).
                 Symmetric — checks both before and after each dream.

Track Knowledge Status progression across your Review (REV) entries.

Shows how topics move through Needs Work → Solid → Mastered over time,
based on the Knowledge Status field on each REV page.

Args:
    topic: Optional # topic tag to filter (e.g. "calculus"). Leave blank
           to show all topics across all REV entries.

Independently check a Review page's claimed Knowledge Status against
evidence in the journal, then prepare a dialogue over anything that
doesn't line up — e.g. a topic marked Mastered that still has open
questions attached to it.

This runs AFTER a REV page exists — never before; there's nothing to
audit until a status has actually been claimed. If no REV page is
found, the tool declines. This tool does NOT write to the database —
it prepares the audit and dialogue instructions for Claude to run in
this conversation. Call `commit_assessment()` after the user reviews
the outcome, to persist it. Never changes the REV page's own claimed
status — that stays physical-authority, exactly like
surface_connections never rewrites a SYN page.

A "Needs Work" claim isn't checked against evidence — it doesn't claim
completeness, so there's nothing to hold it to. Only Solid and
Mastered claims get audited.

Trigger phrases: "Audit REV-008", "Check my knowledge status claims
against the evidence".

Args:
    rev_template_id: The REV page's template ID (e.g. "REV-008").
                     Required — the tool declines if no REV page with
                     this ID exists.
    depth:           "brief" | "standard" (default) | "deep" — how many
                     follow-up questions per flagged topic to plan for.
                     The user can also say "more on this one" for any
                     single topic regardless of depth.

Returns the claimed statuses, evidence findings per topic, and audit +
dialogue instructions for Claude to execute.

Store the confirmed outcome of an audit_knowledge_status() dialogue.

Call this after the dialogue concludes and the user has reviewed the
assessment. Only the assessment — what the audit found and what came
of the dialogue, not a re-listing of every open question — is stored
as the entry's text.

Never changes the audited REV page's own claimed status — that stays
physical-authority, exactly like commit_distillation never rewrites a
SYN page. Stores with source='ai_extract' (excluded from journal_health
KPIs) using the AIEX sequence, and links to the REV page with an
asserted 'assesses' edge.

Args:
    assessment_json: JSON string with fields:
      rev_template_id (required) — the REV page this assesses.
      assessment       (required) — 2-5 sentences: what the audit found
                       and what came of the dialogue. This is the artifact.
      reaffirmed, revised — lists of topic strings (both optional,
                       default empty).
      tags             — optional list of "#topic"/"@source"/etc strings.
      date             — optional ISO date; defaults to today.

Returns a confirmation with the assigned AIEX ID and the assesses edge.

Independently check a Dream Capture entry for cross-domain echo — RC/REV
entries sharing a theme within a few days of the dream — and prepare a
dialogue over what, if anything, the dream's symbols mean to you.

This runs AFTER a DC page exists — never before; there's nothing to
bridge until a dream has actually been recorded. If no DC page is
found, the tool declines. Reuses dream_correlation()'s co-occurrence
data (chain 1: composed, not reimplemented) for the cross-domain-echo
half, so the same non-negotiable guardrails apply here too: these are
plain co-occurrence counts, never "correlation," always reported with
window_days, match count, and base rate.

This tool does NOT write to the database — it prepares the findings
and dialogue instructions for Claude to run in this conversation. Call
`commit_observation()` after the user reviews the outcome, to persist
it. Never changes the DC page's own dream narrative — that stays
physical-authority, exactly like surface_connections never rewrites a
SYN page. The artifact this tool exists to produce is a *noticing*,
not a conclusion — at journal scale this dialogue cannot support
calling its output an inference — and never a restatement of the
dream (already stored) or an asserted claim about what a symbol means
(that's the user's call, always asked, never proposed).

Trigger phrases: "Bridge DC-005 to my research", "What does this dream
connect to?".

Args:
    dc_template_id: The DC page's template ID (e.g. "DC-005").
                    Required — the tool declines if no DC page with
                    this ID exists.
    window_days:    How many days apart counts as "near," for the
                    cross-domain-echo check (default 3).
    depth:          "brief" | "standard" (default) | "deep" — how many
                    follow-up questions per topic to plan for. The
                    user can also say "more on this one" for any
                    single topic regardless of depth.

Returns the dream's own content, cross-domain echoes, and dialogue
instructions for Claude to execute.

Store the confirmed outcome of a bridge_dream_research() dialogue.

Named "observation," not "inference": at journal scale (routinely a
handful of DC entries, sometimes one), what this dialogue produces is
a noticing, not a conclusion the data could support calling an
inference. Call this after the dialogue concludes and the user has
reviewed the observation. Only the observation — what the dialogue
revealed, not a restatement of the dream or an asserted symbol
meaning — is stored as the entry's text.

Never changes the bridged DC page's own dream narrative — that stays
physical-authority, exactly like commit_distillation never rewrites a
SYN page. Stores with source='ai_extract' (excluded from journal_health
KPIs) using the AIEX sequence, and links to the DC page with an
asserted 'observes' edge.

Args:
    observation_json: JSON string with fields:
      dc_template_id (required) — the DC page this observes.
      observation      (required) — 2-5 sentences: what the dialogue
                       revealed. This is the artifact.
      confirmed_echoes, symbol_notes — lists of strings (both
                       optional, default empty).
      tags             — optional list of "#topic"/"@source"/etc strings.
      date             — optional ISO date; defaults to today.

Returns a confirmation with the assigned AIEX ID and the observes edge.

Prepare an AI research session for insight extraction.

Loads knowledge base context (existing tags, potentially related entries)
and returns it alongside the session text and extraction instructions.
Claude then performs the extraction in its response to the user.

This tool does NOT write to the database. After the user reviews the
extracted insights, call commit_aiex() to store confirmed entries.

Trigger phrases: "Extract insights from this session", "Run AIEX on this
conversation", "Generate insight extraction report".

Args:
    session_text:    Full or partial transcript of the research session.
    source_platform: Platform where session occurred (e.g. "Claude Desktop",
                     "Claude Mobile"). Leave blank if unknown.

Returns a context block + extraction instructions for Claude to process.

Write confirmed AIEX insights to the knowledge base.

Takes a JSON string conforming to the AIEX-001 schema and stores each
confirmed insight as a separate AIEX-NNN entry. IDs are assigned
sequentially at write time. All entries are tagged as AI-Extracted.

Call this after the user has reviewed and approved the output from
extract_insights().

Args:
    session_json: JSON string with fields: entry_type, date,
                  source_platform, session_focus, insights (list),
                  open_questions (list), action_items (list).
                  Each insight must have: text, confidence_tier, tags,
                  connections.

Returns a confirmation listing every AIEX ID assigned.