Self-Onboarding & Documentation

The hardest part of joining a new engineering team isn't learning the language; it is learning the architecture. You have to trace through hundreds of files just to figure out how a simple User model relates to an Order.

In Carotene, the architecture is not hidden in the implementation. It is explicitly declared in your .carrot files. Because these files are designed to be perfectly readable by both humans and the Carotene AI Compiler, the framework itself becomes your Senior Architect and your Technical Writer.

1. The carrot ask Command

If you are a new developer opening a massive Carotene monorepo for the first time, you don't need to hunt for the documentation. The codebase is the documentation.

You can use the native carrot ask command to query the architecture directly from your terminal.

$ carrot ask "If I want to refund an order, what function do I call and what permissions do I need?"

Because Carotene understands the Abstract Syntax Tree (AST) of your blueprints, it doesn't hallucinate. It reads the exact state of your current commerce.carrot file and responds with precision:

Carotene AI:

To refund an order, you should call the ProcessRefund(orderId: String) function located in the CoreAPIbackend.

Security Requirements:

• You must pass an active session.
• requires session.role == Admin

Side Effects:

• It will update store.Order.status to Refunded.
• It will call integration.Stripe.RefundPayment.

2. Auto-Generated Architecture Diagrams

Visual learners often need to see the system to understand it. In traditional teams, system diagrams are drawn manually in Figma or Miro and become outdated the day after they are created.

Carotene can generate pixel-perfect, mathematically accurate architecture diagrams on the fly:

$ carrot generate:diagram --domain commerce --format html

This command parses your model, flow, and backend blocks and outputs an interactive visual map showing how tables relate, what state transitions are legal, and which external integrations your backends are wired to.

3. IDE Context (The MCP Server)

As discussed on the previous page, the Carotene MCP Server injects your architecture directly into AI-native editors like Cursor or VS Code.

This means a Junior Developer can open a file, highlight an implementation stub, and ask their IDE:

"Why did the AI use the Stripe integration here instead of PayPal?"

The IDE, armed with the Carotene Context Matrix, will instantly reply:

"Because the commerce.carrot blueprint strictly limits the ProcessRefund function to calls integration.Stripe. If I attempted to use PayPal, the Zero-Trust Sandbox would reject the build."

4. Auto-Generated Documentation Portals

For enterprise teams or open-source projects, a terminal command isn't always enough. You need a searchable, highly readable website.

Because Carotene knows every model, function, side effect, and Zero-Trust boundary in your system, it can generate a complete static documentation site with a single command.

$ carrot generate:docs --engine vitepress --out ./docs
# (Also supports --engine docusaurus)

What it generates:

• API References: Complete, typed documentation for every backend function, including request/response payloads.
• Security Matrices: A visual breakdown of the RBAC requires rules and Zero-Trust verbs (reads, updates, calls) for every endpoint.
• Data Dictionaries: A full breakdown of your store models and flow state machines.
• Embedded Diagrams: The interactive diagrams from Step 2 are automatically embedded into the relevant pages.

You can instantly deploy this docs/ folder to Vercel, Netlify, or GitHub Pages. Because it compiles directly from your .carrot files, your documentation is mathematically guaranteed to be 100% accurate to your production code.