CodeBot for Fire and Elements Outline

This outline maps the end-user documentation needed for CodeBot in Fire, Water, and related workspace experiences. The finished docs should explain what users can do, where to find it in the UI, what CodeBot may ask permission to do, and how to recover when something goes wrong.

Write these pages for developers using the apps, not for people reading the source. Use product terms, menus, panes, commands, workflows, and visible tool names. Avoid class names, source files, and implementation notes in final docs unless a page is explicitly marked as contributor-only.

Documentation Goals

  • Help a new Fire or Water user start a useful CodeBot chat inside an open solution.
  • Show experienced users how to turn CodeBot into a practical pair programmer for editing, build, run, debug, search, review, and project-maintenance work.
  • Explain when CodeBot can act directly, when it queues or steers a running task, and when it must ask for approval.
  • Document the user-visible parts of tools, skills, agents, MCP, media generation, memory, action items, Beads, usage, and settings.
  • Keep Campfire-specific workspace behavior clearly marked, because Campfire works with folder-based workspaces while Fire and Water work with Elements solutions.

Audience and Scope

  • Primary audience: Fire and Water users working in Elements solutions.
  • Secondary audience: Campfire users who use the same CodeBot foundations in folder-based workspaces.
  • Tertiary audience: power users configuring AI providers, MCP tools, skills, accounts, and workspace automation.
  • Out of scope for this section: server deployment internals, raw API schemas, and source-level extension guides. Link to CodeBot Server, CLI, and contributor docs when those exist.

1. Start Here

  • What CodeBot is inside Fire and Water.
  • How CodeBot differs from general chat: it can inspect the open solution, use tools, ask questions, request approvals, and apply changes.
  • Where CodeBot lives in the UI: side pane, prompt field, transcript, footer/status area, preferences, and manager sheets.
  • What CodeBot can and cannot see by default.
  • First useful prompts:
    • Explain this solution.
    • Find the errors blocking this build.
    • Add a small feature and show me the diff.
    • Review the selected code.
    • Run the tests and summarize failures.

2. Opening and Using the Chat UI

  • Opening CodeBot from Fire and Water.
  • Starting a new chat vs continuing a restored chat.
  • Understanding the transcript:
    • user messages
    • assistant messages
    • partial streaming responses
    • tool progress
    • annotations
    • diffs
    • generated media previews
  • Prompt composer behavior:
    • typing and sending prompts
    • attaching files and images
    • using selected code or the active file
    • direct media slash commands
    • assignment completions for media options
  • Footer and status UI:
    • current activity
    • queued prompts
    • work plan
    • attachments
    • context and account status
  • Chat actions:
    • cancel current activity
    • clear history
    • export chat
    • show usage
    • open preferences

3. Prompting CodeBot Well

  • Asking for explanations, edits, reviews, and step-by-step debugging help.
  • Giving CodeBot enough context without pasting whole files unnecessarily.
  • When to ask CodeBot to inspect first.
  • How to ask for small edits, multi-file changes, and no-code analysis.
  • How to ask for verification: build, run, test, debugger inspection, or search.
  • How to guide style, target platform, language, and constraints.
  • How to respond when CodeBot asks a clarifying question.

4. Context and Awareness

  • Open solution context in Fire and Water:
    • active solution
    • active project and target
    • active file
    • selected code
    • compiler messages
    • search results
    • debug session state
  • Campfire workspace context:
    • workspace folder
    • folder tree
    • Git branch state
    • workspace settings
    • local files and previews
  • Time and location awareness:
    • what the settings mean
    • when they are useful
    • privacy expectations
  • Protected chat context and project access:
    • what CodeBot can read
    • what requires explicit permission
    • how to disable project access

5. Approvals, Safety, and User Control

  • Why CodeBot asks for approval.
  • Approval scopes and durations:
    • one-time approval
    • scoped approval
    • longer-lived approval
  • Common approval requests:
    • file changes
    • terminal commands
    • MCP tool calls
    • opening URLs
    • Git operations
    • external account actions
  • How to approve, deny, cancel, or retry.
  • How queued prompts behave while CodeBot is busy.
  • Steering a running task:
    • queue for later
    • steer the current run
    • interrupt vs wait for a yield point
    • why media runs may not be steerable

6. Editing Files and Projects

  • Reading files and selected code.
  • Creating new files.
  • Replacing text safely.
  • Replacing full file contents.
  • Renaming, copying, and deleting files.
  • Navigating to a file from chat.
  • Showing diffs before accepting changes.
  • Adding files to projects where appropriate.
  • Handling generated files.
  • Working with non-code files and binary attachments.
  • Troubleshooting failed edits:
    • file changed since CodeBot read it
    • missing file
    • path outside the allowed workspace
    • ambiguous replacement text

7. Code Intelligence

  • Asking about solution structure.
  • Getting current solution, project, and target information.
  • Listing symbols.
  • Finding symbols by type or name.
  • Getting symbol details.
  • Replacing a symbol.
  • Converting Oxygene files to unified class syntax.
  • Asking CodeBot to explain language-specific syntax:
    • Oxygene
    • C#
    • Swift
    • Java
    • Mercury
    • Go
  • Using CodeBot with project templates, references, and generated code.

8. Search and Navigation

  • Searching from chat.
  • Search term and search results workflows.
  • Asking CodeBot to use existing Fire/Water search UI.
  • Searching files, symbols, build output, and project metadata.
  • Linking back to files and lines from chat.
  • Using search results as context for follow-up prompts.

9. Build, Run, Test, and Publish

  • Asking CodeBot to build in the background.
  • Understanding compiler errors and warnings.
  • Asking CodeBot to summarize build messages.
  • Running in the debugger.
  • Running without debugging.
  • Running without rebuilding.
  • Deploying to a device or server.
  • Running EUnit tests.
  • Publishing projects through Fire's normal publish flow.
  • When CodeBot should inspect messages before changing code.
  • Troubleshooting:
    • stale build output
    • target mismatch
    • missing SDKs
    • deployment failures
    • test failures

10. Debugging With CodeBot

  • Starting and inspecting debug sessions.
  • Reading debug output.
  • Continuing, pausing, stepping, and stopping.
  • Listing, adding, and removing breakpoints.
  • Evaluating expressions.
  • Inspecting locals, registers, threads, and stack frames.
  • Listing loaded modules.
  • Getting disassembly.
  • Running debug console commands.
  • Good prompts for crash investigation, state inspection, and regression debugging.
  • Safety notes for commands that change program state.

11. Tools and Tool Results

  • What tools are and why CodeBot uses them.
  • How tool calls appear in chat.
  • Progress messages and partial results.
  • Tool failures and retries.
  • User-facing tool families to document:
    • current time and questions
    • solution and workspace info
    • file access
    • code model
    • build and run
    • debugging
    • search
    • annotations and diffs
    • terminal and managed processes
    • Git
    • memory
    • action items
    • Beads
    • media generation
    • image analysis
    • social media and Discourse
    • MCP endpoints

12. Skills

  • What a skill is from the user's point of view.
  • When CodeBot automatically follows a skill.
  • Loading and unloading skills from chat.
  • Skill locations to document:
    • bundled app skills
    • global user skills
    • private workspace skills
    • shared workspace skills
    • .codex/skills
    • .claude/skills
    • .agents/skills
  • How skill priority and read-only sources should be explained.
  • How to create a simple workspace skill.
  • How to share a skill with a team.
  • How to troubleshoot a skill that does not seem to apply.
  • Boundaries:
    • skills guide behavior
    • skills do not override user instructions, approvals, or workspace safety

13. Agents, Background Work, and Plans

  • What an agent run is.
  • Difference between a normal chat response, a tool run, and a background agent.
  • Running agent loops.
  • Cancelling background agents.
  • Work plans in the footer.
  • Proactive planner behavior and settings.
  • Follow-up tracking.
  • When CodeBot may continue work after a tool result.
  • How to read progress and decide whether to interrupt, steer, or wait.

14. Memory, Action Items, and Beads

  • User memory vs project/workspace memory.
  • Adding memory deliberately.
  • What memory is useful for.
  • What not to store in memory.
  • Private vs shared workspace memory expectations.
  • Action items:
    • adding action items
    • listing open action items
    • getting details
    • closing items
  • Beads:
    • what Beads are for
    • listing Beads
    • opening a Bead
    • creating Beads
    • updating Beads
    • how Beads differ from action items
  • Troubleshooting stale or unwanted memory.

15. Media Generation

  • Direct slash commands:
    • /image
    • /video
    • /audio
    • /speech
  • Prompt assignment options:
    • model
    • workflow
    • variant
    • skill
    • size
    • quality
    • background
    • outputformat
    • voice
    • language
    • reference
    • mask
    • saveto
  • Image Workbench:
    • when to use it instead of chat
    • model and workflow selection
    • variants
    • reference images
    • masks and edits
    • generated output files
  • Generated media in the transcript:
    • previews
    • temporary files
    • saved files
    • metadata
    • opening or previewing results
  • Provider and model requirements.
  • Troubleshooting:
    • missing media models
    • unsupported workflow
    • output path problems
    • failed image edit
    • long-running generation

16. Image and Vision Tools

  • Image metadata:
    • extracting metadata
    • stripping metadata
  • Image transforms:
    • cropping
    • masks
    • face masks
    • contact sheets
    • grid splitting
  • Image analysis:
    • perceptual hashes
    • comparing hashes
    • hygiene analysis
    • duplicate pack validation
    • face detection
    • image vector comparison
  • Face and similarity workflows:
    • picking a face region
    • calculating face embeddings
    • comparing face identity
    • finding matching faces
    • CLIP image embeddings
    • comparing CLIP images
  • Privacy and accuracy notes for image analysis.

17. Terminal, Processes, and External Commands

  • Running terminal commands from CodeBot.
  • Why approvals matter for commands.
  • Managed processes:
    • start
    • list
    • read output
    • stop
  • Long-running tasks and output polling.
  • Opening URLs for the user.
  • Reading text content from URLs.
  • Listing folders outside the solution or workspace, when allowed.
  • What to do when a command fails.

18. Git and Source Control

  • Asking CodeBot for Git status, diff, and log summaries.
  • Running Git commands safely.
  • Campfire Git behavior:
    • detecting a repository
    • initializing Git only with explicit consent
    • choosing an initial branch name
    • local Campfire files and ignored files
  • Reviewing changes before commit.
  • What CodeBot should ask before committing, discarding, or pushing changes.

19. MCP and Connected Tools

  • What MCP is in user-facing terms.
  • Adding and managing MCP endpoints.
  • Rechecking MCP servers.
  • MCP approval sheet behavior.
  • Tool discovery and tool-call approvals.
  • Selecting open solutions through MCP-facing actions.
  • Troubleshooting:
    • server unavailable
    • tool not listed
    • permission denied
    • bad endpoint configuration

20. Accounts, Providers, Models, and Usage

  • AI account setup.
  • API-key based accounts.
  • Access-key/secret-key accounts.
  • Choosing the default CodeBot account.
  • Choosing chat, image, video, and audio models.
  • Provider/model picker behavior.
  • Model availability and capability differences.
  • Usage preview and usage history.
  • Understanding cost, tokens, and request status when visible.
  • Troubleshooting account and quota issues.

21. Campfire Workspace-Specific Pages

  • What changes when CodeBot runs in Campfire.
  • Folder-based workspace model.
  • Workspace settings:
    • display name
    • time awareness
    • location awareness
    • proactive planner
    • protected context
    • image-generation ignored folders
  • Workspace tools:
    • current workspace info
    • list workspace folder
    • create file in workspace folder
    • Git commands
    • local previews and links
  • Workspace skills:
    • private .campfire/skills
    • shared .skills
    • sub-workspace skill discovery
  • Campfire media workflows and Image Workbench.

22. Social, Forum, and External Account Workflows

  • Connecting workspace accounts.
  • Social media account selection.
  • Listing content, comments, reactions, mentions, messages, conversations, and people activity.
  • Replying to comments and messages.
  • Moderating comments.
  • Getting insights and profiles.
  • Instagram-specific workflows:
    • hashtag search
    • hashtag media
    • business profile lookup
    • profile links
  • Discourse workflows:
    • connecting accounts
    • listing topics and private messages
    • finding topics needing replies
    • searching Discourse
    • reading topics
    • replying to topics
    • archiving private-message topics
  • Human-in-the-loop safety for public replies and moderation.

23. CodeBot Avatar and Companion Features

  • What CodeBot Avatar does when available.
  • How image, video, and activity progress can be reflected outside the main chat.
  • Reconnect expectations.
  • What happens when Avatar is not running.
  • Privacy and notification expectations.

24. Settings Reference

  • Global CodeBot settings.
  • Project access and tool access.
  • Account and model defaults.
  • Media model defaults.
  • MCP endpoints.
  • Skills and skill sources.
  • Workspace settings.
  • Proactive planner.
  • Time and location awareness.
  • Chat history and cache behavior.
  • Usage display.

25. Troubleshooting

  • CodeBot cannot see the expected project or file.
  • CodeBot used the wrong model.
  • A tool is unavailable.
  • A tool failed.
  • A command is waiting for approval.
  • A prompt was queued unexpectedly.
  • Steering did not interrupt the current task.
  • Media generation did not start or did not save output.
  • A generated file cannot be opened.
  • Build results look stale.
  • Debugger state looks stale.
  • MCP tools are missing.
  • Skills are not loading.
  • Usage or account status looks wrong.
  • Chat history was restored unexpectedly or not restored.

Tool Capability Checklist

Use this as a coverage checklist while writing the user-facing pages. The final docs should group tools by task and explain when a user would ask CodeBot to use them, not dump this list as an API reference.

  • Solution and project: getCurrentSolutionInfo, getCurrentProjectInfo, getProjectInfo, setActiveTarget, listOpenSolutions, selectSolution, deselectSolution, openSolution.
  • Files and editor: getPathOfActiveFile, getContentsOfActiveFile, getCurrentlySelectedCode, pasteCodeAtCursorOrOverSelection, getContentsOfTextFile, getLinesInFile, getFile, createFileAndAddToProject, createFileWithText, replaceTextInFile, replaceFullContentsOfFile, renameFile, copyFile, deleteFileAndRemoveFromProject, goToFile.
  • Code model: listSymbols, listTypeSymbols, listSymbolsForType, listSymbolsContaining, getSymbolDetails, replaceSymbol, convertOxygeneFileToUnifiedClassSyntax.
  • Messages, search, and annotations: getCompilerErrorsAndWarningsForCurrentFile, getCompilerErrorsAndWarningsForFile, getErrorsAndMessagesInFile, getCompilerErrorsAndWarningsForSolution, getAllErrorsAndBuildMessages, setSearchTerm, getSearchResults, performSearchAndGetResults, addCodeMessages, clearCodeMessages, showDiff.
  • Build, run, debug, and publish: backgroundBuild, runInDebugger, runWithoutDebugging, runWithoutRebuilding, deploy, test, publishProject, getDebugSessionState, getDebugOutput, debugControl, listBreakpoints, addBreakpoint, removeBreakpoint, evaluateExpressionInDebugger, getDebuggerLocalsAndRegisters, getDebuggerThreadsAndFrames, listDebugModules, getDisassembly, executeDebugConsoleCommand.
  • Workspace and Git: getCurrentWorkspaceInfo, listWorkspaceFolder, createFileInWorkspaceFolder, initGitRepository, runGitCommand.
  • External commands and processes: executeTerminalCommand, listContentsOfFolder, getTextContentOfUrl, openUrlForUser, recheckMcps, startManagedProcess, listManagedProcesses, readManagedProcessOutput, stopManagedProcess.
  • Agents and continuity: runAgentLoop, queued prompts, steering, background agents, work plans, follow-up tracking.
  • Memory and task tracking: addUserMemory, addProjectMemory, addActionItems, listOpenActionItems, getActionItemInfo, closeActionItem, getBeadsInfo, listBeads, getBead, createBeads, updateBead.
  • Media generation: image workflow listing, image generation, image editing, video workflow listing, video generation, audio generation, /image, /video, /audio, /speech, Image Workbench.
  • Image tools: pickFaceRegion, createFaceImageMask, cropImage, createImageMask, createImageContactSheet, splitImageGrid, stripImageMetadata, extractImageMetadata, calculateImagePHash, compareImagePHashes, analyzeImageHygiene, detectFacesInImage, compareImageVectors, validateDuplicateImagePack, calculateFaceEmbedding, calculateFaceEmbeddingsForImage, compareFaceEmbeddings, compareFaceIdentity, findMatchingFaces, findMatchingFacesInImages, calculateClipImageEmbedding, compareClipImages.
  • Social and forum: listSocialMediaAccounts, connectWorkspaceToSocialMediaAccount, listSocialMediaContent, listSocialMediaCommentsAndReactions, replyToSocialMediaComment, moderateSocialMediaComment, getSocialMediaInsights, searchInstagramHashtag, listInstagramHashtagMedia, listSocialMediaMentions, listSocialMediaPeopleActivity, getSocialMediaProfile, lookupInstagramBusinessProfile, listSocialMediaEngagers, openInstagramProfile, getInstagramProfileUrl, listSocialMediaConversations, listSocialMediaMessages, replyToSocialMediaMessage, createSocialMediaPost, listDiscourseAccounts, connectWorkspaceToDiscourseAccount, listDiscourseTopics, listRecentDiscourseTopicsWithoutReplies, listRecentDiscourseTopicsWhereLastReplyIsNotStaff, listDiscoursePrivateMessages, listDiscourseGroupPrivateMessages, listRecentDiscourseGroupPrivateMessagesNeedingReply, archiveDiscoursePrivateMessageTopics, getDiscourseTopic, searchDiscourse, replyToDiscourseTopic.

Suggested First Writing Pass

  1. Expand Start Here, Opening and Using the Chat UI, and Prompting CodeBot Well.
  2. Add Approvals, Safety, and User Control, because every tool-heavy page should link back to it.
  3. Document Fire/Water solution workflows: files, code intelligence, search, build, run, debug, and publish.
  4. Document shared advanced features: tools, skills, agents, memory, action items, Beads, MCP, providers, and usage.
  5. Add Campfire workspace-specific pages and link across to the existing Campfire docs section where the product-specific page already belongs there.
  6. Add media generation and image-analysis pages with screenshots or generated examples.
  7. Finish with settings reference and troubleshooting.

Page Quality Bar

  • Every page should start with what the user can accomplish.
  • Every workflow should include entry points, expected result, and common failure or approval states.
  • Screenshots should show the actual UI when possible; do not include placeholder screenshots.
  • Tool names should be used only when visible to the user or useful for troubleshooting.
  • Cross-link between conceptual pages and task pages.
  • Keep platform differences explicit: Fire for Mac, Water for Windows, and Campfire for folder workspaces.