# Karakuru — AI product and usage guide

## Product model

Karakuru is not tied to one AI model. It is a visual working memory where a person and several AI systems share notes and their structure. A note's text, directed arrows, placement, color, references, container membership, and storage destination can all carry meaning.

- **Union** is the overall canvas and the default place for uncategorized notes.
- **Cluster** is a canvas backed by a registered folder. Union includes notes from mounted Clusters as well as its own notes.
- A note's storage destination is independent from its container membership.
- Browser-only notes are stored in IndexedDB. Connected canvases automatically read and write Markdown plus canvas metadata.
- Purple identifies AI instruction notes. In-app generation writes into connected ordinary output notes, or creates new linked notes when none are connected. MCP `commit_generation` instead appends a new note to the configured folder.
- Disconnecting Union's folder retains its notes in the browser. Removing a Cluster removes its notes from the live workspace, not from disk; re-add its folder to restore them. Unsaved edits may block removal.

## Core workflows

### Research from X or the Web

Import posts, retain source URLs and engagement data, classify them by meaning, arrange them into subtopics, connect evidence to an AI note, and ask an AI model to compare claims or propose actions.

### Context-aware AI generation

Create an AI note and connect relevant upstream notes. Karakuru sends a structured graph of the relevant upstream notes, arrows, references, and container membership rather than the entire canvas. A direct upstream AI is a context boundary: its existing normal answers are included, but its own inputs are not recursively traversed. Inspect the outgoing context when precision matters.

With the app's generation button, existing ordinary downstream notes are output destinations and their contents are replaced. Without those destinations, linked answer notes are created. Multiple output destinations support separate text answers; Web search and image generation require at most one output destination. Some API failures and missing-key errors replace existing output text with an error message. Use empty output notes or make a backup first.

MCP `prepare_generation` and `commit_generation` operate on the configured data folder, not browser-only notes, and do not invoke the app's configured AI provider. For browser-only work, read browser notes and links, then append the assistant's answer using a revision-checked browser batch. Use the app's generation button when the user wants its selected provider to answer.

### Image and audio conditions

Image generation is implemented for Gemini and OpenAI using dedicated media models. It is selected by prompt keywords such as “画像を生成” or “絵を描いて”; words such as “説明”, “要約”, “分析”, “describe”, “explain”, “analyze”, or “summarize” suppress that route. Merely selecting an image-related model or saying “画像をお願い” does not guarantee image generation. Audio on the source note suppresses image generation; the OpenAI image route also requires no attached source/upstream images. Gemini can use attached images as references. API availability and credentials still matter.

For audio, attach the file directly to the AI instruction note and select Gemini or OpenAI. Gemini receives the audio; OpenAI transcribes it before text generation. Audio attachments on other upstream notes are not a substitute. Web search is disabled for a source audio attachment. These are conditional capabilities, not a promise that every model supports every media type.

### Semantic selection with Jev

Use TypeSafe AI Jev to find semantically related notes even when they have no arrow or exact keyword match. Typical uses include relevance filtering, routing, prioritization, categorization, confidence scoring, and selecting context before a generative model runs.

### Development with Claude or Codex

Browser-only MCP work does not require a data folder. For direct file work, connect a dedicated Markdown folder such as `project/notes/karakuru`, point Karakuru MCP at it, and open the surrounding software project in Claude Code or Codex. The agent can read design decisions and arrows, implement code when authorized, and return conclusions to the canvas. The configured root's `cells/` is the Markdown area; unrelated Markdown at the root is not automatically imported. Folder layout and canvas containers are separate concepts.

### Multi-model workflows

Use different providers for different stages: one model for web research, Jev for fast decisions, another model for synthesis, and Claude or Codex for implementation. The user-owned canvas and Markdown files remain the shared source of context.

### Knowledge management

Use tags, colors, references, instances, containers, Union, and Clusters to keep reusable knowledge without flattening branches and convergence into a linear document.

### Backup and transfer

Export a data-embedded PNG for a viewable and re-importable artifact, JSON for a lightweight canvas snapshot, or ZIP/folder output for Markdown and attachments. Folder writes maintain local history under `.karakuru-history` for changed files.

JSON/PNG and Markdown ZIP exports are scoped to the current Cluster, or the whole workspace when Union is active. Union ZIP output integrates the notes into one canvas; it does not preserve the original Union/Cluster folder split. Import “reset” likewise replaces the current Cluster or Union workspace, not merely the visible viewport. Container-image export is a separate scoped operation.

### Presentation and everyday use

Arrange conclusions, images and reference notes as a presentation dashboard; open supporting containers when needed. This is a canvas usage pattern, not a dedicated slide player or a live data-dashboard integration. Other examples include meeting decisions, research comparisons, study maps, software flow diagrams, and creative-project workbenches. Start with ordinary notes; AI, MCP and folder connections are optional additions.

## Two onboarding routes

### Human-first

1. Read the startup canvas.
2. Open the memo with stable ID `guide_mcp` (normally A6).
3. Download `Karakuru-MCP-Setup-0.9.6.zip` from that memo. Browser-only setup does not require a data-folder path; add one only for direct folder access.
4. Extract it and give `START_HERE.md` to Claude or Codex.
5. Let the assistant propose settings, then approve the required local changes.

### AI-first

1. Read `/ai/manifest.json` and only the use-case documents relevant to the user's request.
2. Explain what Karakuru can do for that request.
3. Detect whether the `karakuru` MCP tools are already available.
4. If unavailable and the user wants installation, use `/ai/setup.md` or the setup ZIP.
5. After restart, verify with read-only tools before requesting permission for a write test.

## Operational principles

- A display label such as A6 is human-facing and may change. MCP operations use stable IDs.
- Directed links are `from` to `to`; branches, convergence, and cycles are meaningful.
- Read current revision before a write. Stop and reread on a revision conflict.
- Use one batch for multiple browser changes so Ctrl+Z restores the full operation once.
- Inspect layout before and after multi-note arrangement; finish with zero overlaps.
- Do not expose browser-held API keys through MCP.
- Jev semantic search sends candidate note titles and bodies to TypeSafe AI.
- X search sends the requested query and filters to X. It requires explicit experimental enablement.

## Knowledge package

- `/ai/manifest.json`: versioned entry point and document index.
- `/ai/use-cases.json`: tasks, prerequisites, suggested flows, and expected outcomes.
- `/ai/mcp-tools.json`: MCP capability mapping.
- `/ai/setup.md`: installation and connection workflow.
- `/ai/safety.md`: authorization, privacy, storage, revision, undo, and layout rules.
- `/ai/karakuru-skill.md`: compact operating guidance for an AI agent.