Skip to main content

​
Documentation Update To-Do List

This document outlines the necessary updates for the CoralOS documentation to align it with the current state of the coral-server (v1.1.0+).

​
General notes on documenting

​
Codewiki / deepwiki

It’s recommended to use deepwiki, accessible by the codewiki tool in order to ask questions about the codebases efficiently. Alternatively and additionally, the repos are temporarily cloned here. Relevant repos: https://github.com/Coral-Protocol/console - public. Temporarily cloned at ./codebases/console https://github.com/Coral-Protocol/coral-server - public. Temporarily cloned at ./codebases/coral-server https://github.com/Coral-Protocol/coralizer - public. Temporarily cloned at ./codebases/coralizer https://github.com/Coral-Protocol/coral-koog-agent - public. Temporarily cloned at ./codebases/coral-koog-agent https://github.com/Coral-Protocol/cloud - private. Temporarily cloned at ./codebases/cloud-codebase Only the public repos can be accessed with deepwiki. The repo name would be e.g. ‘Coral-Protocol/coral-server’. Deeowiki is an AI-generated wiki that is generally very close to true, though it is closer to the code than appropriate and doesn’t show the most relevant information or guidance sometimes. It is generally advisable to use ask_question, read_wiki_contents and read_wiki_structure for most tasks as the primary starting point, though do still cross-reference with the local code and confirm.

​
TODO comments

Leave TODO comments in the mdx files where relevant, such as where an image/illustration is needed, or some unavailable information is needed to prevent the docs from being vague, incomplete or inaccurate.

​
Phase 1: Global Identity & Standardizations

Foundational changes that align terminology and basic configuration across the entire documentation set. (“Coralized agent” is less desired terminology nowadays, it makes sense only in direct context of the coralizer)
  • Standardize Terminology (Actors → Agents): Replace all mentions of “Actors” with “Agents” (except where referring to the Actor model conceptually).
    • Where to look:
      • about.mdx: Lines 14, 15 (links to /concepts/Actors).
      • docs.json: Redirect at line 15 (Check if other redirects are needed).
      • Global search for “Actor” in all .mdx files.
    • Source of truth: The project’s renaming of “Actors” to “Agents”.
  • Rename “Coral Studio” to “Coral Console”: Update all references and document the new local URL.
    • Where to look:
      • about.mdx: Update card (Line 29).
      • concepts/coral-server.mdx: Update line 21.
      • features/telemetry.mdx: Update line 16.
      • guides/writing-agents.mdx: Update line 11.
      • concepts/sessions.mdx: Update line 20.
      • guides/integrating-with-your-app.mdx: Lines 85, 91, 95, 112, 121, 123.
      • concepts/coral-studio.mdx: Full audit and rename file to concepts/coral-console.mdx.
    • Source of truth: ConsoleConfig.kt (Refers to /ui/console).
  • Standardize “Coralizer” Spelling: Ensure consistent spelling of “Coralizer” (with a ‘z’).
    • Where to look:
      • concepts/agents.mdx: GitHub link (Line 18) and spelling (Line 19).
      • concepts/coral-server.mdx: Diagram/text (Line 42).
      • guides/installation.mdx: “Managing Agents” section.
      • docs.json: Title of the coralizer section.
    • Source of truth: Project standardization on “Coralizer” (z).
  • Standardize Ports (3001 → 5555): Consistently use port 5555 as the default.
    • Where to look:
      • guides/installation.mdx: Lines 25, 38, 58 (change 3001 to 5555).
      • quickstart/coral-agent.mdx: Lines 18, 21.
    • Source of truth: NetworkConfig.kt (bindPort = 5555u).
  • Update Versioning Reference (1.0 → 1.1.0+): Ensure all version mentions are current.
    • Where to look:
      • guides/writing-agents.mdx: Version note (Line 11).
      • guides/docker-in-docker.mdx: Version note (Line 11).
      • guides/integrating-with-your-app.mdx: Version note (Line 11).
      • guides/installation.mdx: JAR filename example (Line 48).
      • cloud/using-api.mdx: version: '1.0.0' in examples.
      • configuration/agent.mdx: Version strings in examples.
    • Source of truth: coral-server/gradle.properties (version=1.1.0).

​
Phase 2: Core Platform Concepts (Architecture)

Documenting the underlying logic and system design of CoralOS v1.1.0.
  • Document Modular Architecture: Explain the Ktor/Koin module system.
    • Where to look: New section in concepts/coral-server.mdx.
    • Source of truth: Main.kt and the modules/ directory (config, logging, blockchain, network, agent, session).
  • Update Agent Lifecycle: Document the flow from Registry → Request → Resolved → Runtime.
    • Where to look: Update “How it works” in concepts/coral-server.mdx (Line 35+).
    • Source of truth: AgentGraphResolver.kt and AgentRuntime.kt.
  • New: MCP Integration Guide: Document how agents use MCP to interact with sessions and threads.
    • Where to look: Create concepts/mcp.mdx.
    • Source of truth: org.coralprotocol.coralserver.mcp and McpRoutes.kt.
  • New: Multi-Agent Coordination: Document the thread-based communication model (filtering, waiting, blocking).
    • Where to look: Create concepts/coordination.mdx.
    • Source of truth: coral-server wiki (Section 9) and agent/runtime/ coordination logic.
  • Expand: Session Persistence & Webhooks: Document SessionPersistenceMode and webhook configuration.
    • Where to look: Expand concepts/sessions.mdx.
    • Source of truth: SessionRuntimeSettings.kt and LocalSessionManager.kt.

​
Phase 3: Configuration & CLI Tools (Setup)

Technical specifications for configuring agents and using management tools.
  • Update coral-agent.toml Specification:
    • Update edition to 3 and mark 1 & 2 as unsupported.
    • Remove number and secret types (dropped in favor of specific types).
    • Document new runtime options and transport configurations (SSE vs Stdout).
    • Where to look: configuration/agent.mdx.
    • Source of truth: RegistryAgent.kt (edition = 3) and AgentOption.kt.
  • New: Registry Configuration Guide: Document FileAgentRegistrySource and directory auto-scanning.
    • Where to look: Create configuration/registry.mdx.
    • Source of truth: RegistryConfig.kt (localAgents, rescan timer).
  • New: Environment Variables Reference: List all CORAL_* variables for server and agents.
    • Where to look: Create configuration/environment-variables.mdx.
    • Source of truth: SessionAgentExecutionContext.kt (Agent variables) and RootConfig classes.
  • New: Coralizer Tool Guide: Document the CLI tool, mcp command, and framework templates.
    • Where to look: (Removed) Link to https://github.com/Coral-Protocol/coralizer instead of maintaining a docs page; page removed from navigation.
    • Source of truth: coralizer repository (main.rs, mcp_server.rs, frameworks/).

​
Phase 4: Updated Developer Guides (Implementation)

Actionable guides for building and debugging agents.
  • Update: Writing Agents:
    • Update examples to edition = 3.
    • Update “Orchestration Environment” with full CORAL_* variable list.
    • Reference coral-koog-agent as the primary modern implementation example.
    • Where to look: guides/writing-agents.mdx.
    • Source of truth: SessionAgentExecutionContext.kt and coral-koog-agent repo.
  • Update: Integrating with your App: Update “Custom Tools” for v1.1.0 webhook/tool call handling.
    • Where to look: guides/integrating-with-your-app.mdx.
    • Source of truth: LocalSessionManager.kt and SessionRuntimeSettings.kt.
  • Update: Docker-in-Docker: Ensure /var/run/docker.sock mounting instructions are current.
    • Where to look: guides/docker-in-docker.mdx.
    • Source of truth: DockerConfig.kt.
  • New: Agent Debugging Tools: Document Puppet API and built-in debug agents (Echo, Seed, Tool).
    • Where to look: Create guides/debugging-agents.mdx.
    • Source of truth: PuppetApi.kt and agent/debug/ package.
  • Audit: Welcome & Quickstart: Ensure Quickstart points to Coralizer as the recommended starter.
    • Where to look: welcome.mdx (Quickstart link).
    • Source of truth: Transition to coralizer as the primary tool.

​
Phase 5: Ecosystem & Monetization

Documenting the marketplace, payments, and security.
  • Expand: Marketplace Integration: Cover v1.1.0 API integration and attestation.
    • Where to look: concepts/marketplace.mdx and configuration/agent.mdx.
    • Source of truth: RegistryApi.kt and MarketplaceAgentRegistrySource.kt.
  • Rewrite: Payments & x402 Flow: Document HTTP 402 flow and Solana-based payments.
    • Where to look: concepts/payments.mdx and new features/payments-x402.mdx.
    • Source of truth: org.coralprotocol.coralserver.x402 and PaymentConfig.kt.
  • Note: Payments/Remote Status: Explicitly state that remote providers/payments are temporarily disabled in v1.1.0.
    • Where to look: concepts/agents.mdx and concepts/payments.mdx.
    • Source of truth: GraphAgentProvider.kt (Remote disabled).
  • New: Authentication & Security Guide: Document auth.keys and SessionAgentSecret.
    • Where to look: Create configuration/security.mdx.
    • Source of truth: AuthConfig.kt and SecurityConfig.kt.

​
Phase 6: Infrastructure & Monitoring

Operations, telemetry, and future network design.
  • Update: Telemetry Integration: Document OpenAI-compatible or generic telemetry exporters.
    • Where to look: Expand features/telemetry.mdx.
    • Source of truth: Telemetry.kt models and API routes.
  • New: Troubleshooting & Logs: Document the new logging system and ~/.coral/logs/.
    • Where to look: Create help/troubleshooting.mdx.
    • Source of truth: LoggingConfig.kt.
  • New: Distributed Agent Network: Document federated servers and distributed architecture (Experimental).
    • Where to look: Create concepts/distributed-network.mdx.
    • Source of truth: GraphAgentServer.kt.

​
Phase 7: Final Cleanup & Sweep

Polishing, link checking, and removing out-of-date markers.
  • Update: Cloud API: Update endpoints (api.coralcloud.ai) and serialization formats.
    • Where to look: cloud/using-api.mdx.
    • Source of truth: NetworkConfig.kt and AgentGraphRequest.kt.
  • Cleanup: Cloud Legal/Corporate: Review TOS and Privacy for placeholder text.
    • Where to look: cloud/tos.mdx and cloud/privacy.mdx.
  • Review: Orphaned Files: Decide on the status of files missing from docs.json navigation.
    • Where to look: Compare file system (examples/, guides/, use/) with docs.json.
  • Editorial Cleanup (about.mdx): Fix broken links to /concepts/Actors and remove informal sentences.
    • Where to look: about.mdx: Lines 14, 15.
  • Final Sweep: Remove Out-of-Date Warnings: Once pages are updated, remove generic <Warning> blocks.
    • Where to look: All .mdx files listed in the original sweep (approx. 25 files).