Reference and Map

A quick index into the codebase: what each command does, where each package lives, the types worth knowing, and the vocabulary the rest of this map uses.

Command surface

main.go registers seven commands on the fisk-ai root. Each is defined in its own *_command.go file.

Command	What it does	File
`run`	Drives the agent loop against a prompt; the default face. Flags include `--checkpoint`, `--resume`, `--chat`, `--no-tui`, `--tool-output`.	`run_command.go`
`session`	Lists, shows, and removes checkpointed sessions (`ls`, `show`, `rm`); `show --transcript` opens the viewer.	`session_command.go`
`info`	Prints the resolved tool table, gated commands, and prompt without calling the model.	`info_command.go`
`knowledge`	Builds and inspects the local RAG index behind `knowledge_search` (`index`, `search`, `show`, `sources`, `rm`, `reset`, `doctor`, `stats`); aliased `rag` and `k`.	`rag_command.go`
`mcp`	Serves the tools over MCP for an external client.	`mcp_command.go`
`a2a`	Serves the tools over NATS for peer agents.	`a2a_command.go`
`discover`	Sends an A2A discovery request and prints a peer’s agent card.	`discover_command.go`

Source-file map

Package	Responsibility	Key files
`main` (root)	CLI wiring, flag parsing, mode and UI selection, signal contract.	`main.go`, `run_command.go`, `run_events.go`, `run_tui_events.go`, `resume_replay.go`, `rag_command.go`
`config`	The single `agent.yaml` schema, mode-based validation, accessors.	`config.go`
`internal/util`	The shared core: introspection, tool params, built-ins, confirm gate, prompter, LLM call, stats.	`fisk.go`, `anthropic.go`, `builtin.go`, `builtin_memory.go`, `builtin_rag.go`, `confirm.go`, `prompter.go`, `llm.go`
`internal/agent`	The agentic loop: setup, iteration, events.	`agent.go`, `runner.go`, `events.go`
`internal/runstate`	Durable sessions: records, fold, store, fingerprint, locking.	`record.go`, `state.go`, `store.go`, `filestore.go`, `fingerprint.go`
`internal/memory`	The pluggable memory store and file backend.	`store.go`, `file.go`, `frontmatter.go`, `key.go`
`internal/rag`	The local RAG index: SQLite store, chunking, hybrid search, embeddings, doctor, write lock.	`store.go`, `chunk.go`, `index.go`, `search.go`, `embed.go`, `doctor.go`, `vec.go`, `lock_unix.go`
`internal/tui`	The full-screen runner and transcript viewer.	`viewer.go`, `live.go`, `prompter.go`, `splash.go`
`internal/mcpserver`	Serving tools over MCP.	`mcpserver.go`
`a2a`	Transport-agnostic A2A protocol types.	`messages.go`, `block.go`, `header.go`, `types.go`, `schemas.go`
`internal/a2anats`	The NATS binding for A2A.	`client.go`, `server.go`, `a2anats.go`, `header.go`
`internal/remotetools`	Import policy for tools pulled from a peer.	`remotetools.go`

Key types

Type	Role	Explained in
`util.Tool`	A single introspected command as a tool: path, model, schema, tags.	Tools and Introspection
`config.Config`	The parsed `agent.yaml` for any mode.	Architecture
`agent.runner`	The loop state, split into rebuilt infrastructure and resumable state.	The Agent Loop
`util.ConfirmGate`	The default-deny approval enforcement for gated commands.	Safety and Human in the Loop
`runstate.RunState`	The folded, resumable state of a run.	Sessions and Resume
`runstate.Fingerprint`	The configuration hash that guards a resume.	Sessions and Resume
`memory.Store`	The pluggable key/value backend interface.	Memory
`rag.Store`	The SQLite-backed knowledge index: chunk, embed, hybrid search.	Knowledge and RAG
`tui.Live`	The full-screen live-run controller.	The Terminal UI
`a2a.Header`	The self-describing framing on every A2A message.	Interoperability

Glossary

Tool: A single runnable fisk leaf command exposed to the model, named by its command path joined with underscores.
Introspection: Running a fisk binary with `--fisk-introspect` to read its command tree as a model.
Deferral: Sending tool definitions on demand through the tool-search tool once the set reaches ten tools, rather than all up front.
Confirm gate: The default-deny check that makes an operator approve a command tagged `ai:confirm` or a `confirm_tags` tag before it runs.
HITL: Human in the loop: the `ask_human_*` tools the model can call to ask the operator a question.
Journal: The append-only record stream a checkpointed run writes to disk, event by event.
Fold: Replaying a record stream into a resumable `RunState` with no IO.
Fingerprint: A hash of model, prompt, tool set, thinking mode, and budgets that must match for a resume to proceed.
Identity: An agent's logical name, defaulting to the binary base name, used for the memory directory and the A2A subjects.
Elicitation: The MCP mechanism by which a served command asks the calling client to approve it.
Agent card: An A2A agent's self-description: name, version, protocols, and tools.
RAG: Retrieval-augmented generation: searching a local document index and feeding the matches to the model as grounding.
Chunk: A heading-delimited, size-packed slice of a document, the unit that is indexed, ranked, and cited.
Lexical tier: The always-on FTS5/BM25 full-text search over chunks; needs no model or server.
Vector tier: The opt-in semantic search: chunk embeddings in sqlite-vec, matched by nearest neighbor.
RRF: Reciprocal Rank Fusion: combining the lexical and vector rankings by rank rather than score, with constant K=60.
Citation: A `relpath#ordinal` token naming a chunk, resolvable back to full text by `knowledge show`.

Back to the start

Return to the Code Map overview for the system-at-a-glance diagram and the mental model.