Gentic Brain — Documentation

Capture a hosted source into Gentic Brain by pasting its public URL. v1 supports **Google Docs** (paste any docs.google.com/document/... share link), **PDFs** (Drive PDF share links, or direct `.pdf` URLs hosted anywhere — Drive, S3, an internal docs server, etc.), and **web pages** (any public http(s) URL — Notion published pages, blog posts, help articles, public spec pages, agency reports). The Modal worker translates share-URLs to the actual content-fetch URL on its side, OCRs image-heavy PDFs, scrapes HTML pages, chunks, embeds, and stages the markdown — findable via `brain_query` and promotable into a curated wiki entity via `wiki_ingest_source`. **Requires the source to be publicly accessible** (Anyone-with-link for Drive content, no auth wall for web pages) — private files and auth-walled pages return a clear actionable error. Processing is async — the tool returns immediately with `status: "processing"` and the source becomes searchable shortly after. Optional `describe_images=true` on web-page captures invokes Gemini Vision on the page's images and folds the descriptions into the captured content — useful for image-heavy pages (marketing emails, ad creatives, social posts) where alt-text is sparse. Per-image cost (~5¢) is billed as a separate line item, capped at 20 images per page, and requires the org to have opted in via the dashboard. When the org hasn't opted in, `describe_images=true` silently downgrades to text-only capture.

Capture a raw text blob into Gentic Brain — for document-shaped text that arrived through a channel with no fetchable URL (creator emails from influencer seeding, pasted Slack quotes, inbound form submissions, etc.). The Modal worker chunks, embeds, and stages the text alongside Brain's document/web captures — findable via `brain_query` and promotable into a curated wiki entity via `wiki_ingest_source`. Use `brain_capture_document` instead when the source has a public URL (Google Doc share link, web page, PDF). Typed event records (reviews, social comments, support tickets, etc.) belong in the activity substrate and have their own capture tool — do NOT use this for those. Processing is async — the tool returns immediately with `status: "processing"` and the text becomes searchable shortly after. Billed per chunk (1¢/chunk) on completion.

Ask a natural-language question against the organization's full brain — both the raw machine memory (knowledge: Slack captures, PDFs, web pages, inbound emails, e-commerce events) and the team's deliberate writing (curated wiki entities). Returns a synthesized grounded answer with clickable citations resolved back to originating systems (Slack permalinks, PDF/web URLs, wiki page URLs). The team's deliberate writing is treated as authoritative on conflicts; raw captures provide supporting context. **Render every returned citation as a clickable markdown link using `view_url` when present, falling back to `source_uri` for non-URL identifiers (e.g. `slack://...` — your Slack-aware renderer should turn these into workspace permalinks).** Use this for any 'what does the company know about X?' / 'why did we decide Y?' / 'how do we handle Z?' question. For consulting only the curated wiki, use `wiki_query` instead.

Aggregate the current Brain state for the org in one read-through call. Returns counts of captured sources, knowledge chunks, wiki entities, and wiki notes; the 10 most recently captured sources + 10 most recently updated wiki entities; and the last 7 days of brain events as a chronological feed (capped at 100). No new persistent store — pure reads from per-org MotherDuck and S3. Used by the Brain dashboard panel in gentic-web; agents can call it to summarize 'what does the brain know about us?' in one round-trip. Free.

Promote a previously-staged source (captured via wiki_stage_source) into the wiki by its canonical source_uri. Resolves (source_type, slug) from the per-org knowledge layer, constructs the staged S3 key, and invokes wiki_ingest's synthesis path — updates entity pages, refreshes the index, appends a log entry, writes the verbatim note. Symmetric with wiki_stage_source / wiki_unstage_source (all three Brain primitives identify sources by source_uri). **Idempotent — safe to re-promote.** Re-running on the same source_uri updates the existing entities in place (was_created=false). **On success the response includes `entity_view_url` for the canonical entity, `wiki_paths` for all entities touched, and `index_view_url` for the updated index — surface these as clickable markdown links in user-facing replies.** Used by gentic-computer's brain_promote_thread intent handler.

Stage an externally-originated source artifact into the brain. Writes the markdown body to the org's S3 wiki-sources prefix, asynchronously vectorizes it into the knowledge layer (searchable via search_knowledge within ~10–60s), and emits a `source_staged` brain event for the ledger. This is the single mandated ingest path — Slack reaction handlers (gentic-computer), future doc-system connectors (Notion / Drive / Confluence), and direct-upload tools all deposit through here. Free; the chained vectorize_content charges its own per-chunk meter on completion. **Idempotent on (source_type, slug)**: re-staging the same source overwrites in place and emits `source_restaged` so the brain doesn't accumulate duplicates from re-reactions or re-syncs.

Soft-delete a previously-staged source by its canonical source_uri. Resolves (source_type, slug) by looking up the knowledge layer, marks all matching knowledge chunks `is_deleted = TRUE`, writes a `.deleted` sidecar marker at the staged S3 key (the original .md is preserved for audit), and emits a `source_unstaged` brain event. Idempotent — subsequent calls on an already-deleted or never-staged source_uri return `soft_deleted: false` with `knowledge_chunks_marked: 0`. Free. Used by gentic-computer's uncapture-intent handler (FR-005). The identity-first design means callers don't need to track the slug separately — passing the same source_uri originally given to wiki_stage_source is sufficient.