# Gakaso — Overview & Getting Started (for AI Agents) > **Audience**: this document is written for AI coding agents (Claude Code, Cursor, and similar) that a Gakaso user runs locally and connects to Gakaso via MCP. It is a service catalog and onboarding overview, not a step-by-step operator manual. For deep click-by-click instructions, the human-facing in-app manual (`/manual`, post-login) is the source of truth — this document intentionally does not duplicate it. ## What is Gakaso Gakaso is an AI-native design canvas — a "semantic Figma" that AI agents can read and write directly, not just view. Where traditional design tools assume a human draws and an engineer later re-implements the result, Gakaso's canvas objects carry structured, machine-readable meaning (component type, intent, constraints, requirement links) from the moment they are created, and that structure round-trips both ways: agents can generate design onto the canvas, and can read the canvas back out as code or as a neutral visual spec. Core ideas an agent should carry into every session: - **AI-first canvas** — every object on the canvas is addressable and mutable through MCP tools, not just through the browser UI. - **Zero handoff** — there is no manual "design → export → re-implement" step. Canvas state is exportable directly to production-ready code or to a neutral spec. - **Two project kinds** — a project is either an **application** canvas (UI screens made of semantic components) or a **diagram** canvas (flowcharts, architecture diagrams, and similar). See `/canvas/application-mode.md` and `/canvas/diagram-mode.md`. - **Faithful round-trip** — real, already-running UI can be imported into Gakaso with pixel/visual fidelity, edited, and read back out without losing that fidelity. See `/mcp/faithful-roundtrip.md`. ## Who does what | Actor | Role | |---|---| | Human user | Creates a Gakaso account, creates project(s), supervises/approves AI-driven changes, does light manual editing in the browser canvas. | | Your local agent (you) | Connects to a specific Gakaso project over MCP using a project-scoped API key, and does the bulk of canvas authoring, diagram creation, imports/exports, and code generation on the human's behalf. | | Gakaso AI (server-side) | An alternative generation path: server-side model calls made by Gakaso itself, invoked from the in-app AI panel rather than by your local agent. Mutually exclusive with your connection for a given chat session — see `/ai/generation.md`. | ## Minimal-input onboarding: what you actually need You do not need a long manual walkthrough to become useful in a Gakaso project. In practice you need only: 1. A **project-scoped API key** (Bearer token) with the scopes relevant to the task — obtained by the human from the project's Settings → API Keys screen, or handed to you directly. 2. The **project ID** you're operating in. 3. The **MCP endpoint** to connect to (Streamable HTTP or stdio, depending on how the human's client is configured). 4. Whatever the human tells you about *intent* — what they want built, imported, or diagrammed. Everything else (which MCP tools to call, which diagram template fits, which design principles to apply) you can resolve yourself from the resources described below. Once connected, two static resources are always available to you without further setup and are worth reading early in a session if the task involves visual output: - `gakaso://diagram-templates/index` and `gakaso://diagram-templates/{category}` — a taxonomy of diagram templates (see `/design/diagram-intelligence.md`), useful whenever a human asks you to "diagram the flow of X" or "show how X works." - `gakaso://manuals/design-principles` and `gakaso://manuals/diagram-selection` — structured guidance for producing higher-quality visual output than an unguided model would produce by default. Both are **unauthenticated MCP resources** — no API key or project binding is required to read them, so you can consult them even before you have project credentials. ## Typical first moves - **"Build me a UI for X"** → connect to the project, read the existing canvas state (`gakaso_list_components` / `gakaso_get_canvas` family), check for an existing Product Design Capsule (`gakaso_get_design_capsule`), then create/update `gks-*` semantic components. See `/canvas/application-mode.md`, `/design/product-design-capsule.md`, and `/mcp/overview.md`. - **"Diagram how X works" / "show me the flow of X"** → consult the diagram template resources, pick the closest-matching template, then create a diagram project or diagram page and populate nodes/edges, then auto-layout. See `/canvas/diagram-mode.md` and `/design/diagram-intelligence.md`. - **"Bring this existing web page/app UI into Gakaso"** → use the faithful import tools (`gakaso_import_ui_snapshot` / `gakaso_import_app_snapshot` / `gakaso_import_live_url`), which require the `frame:import` key scope. See `/mcp/faithful-roundtrip.md`. - **"Get the design back into my codebase"** → use `gakaso_export_faithful` (neutral round-trip, requires `frame:export`) or the code-export tools (`react-tsx` / `html-css` / `react-tailwind`). See `/export.md`. - **"Publish this as a shareable doc"** → use `gakaso_publish_doc`. See `/publish-doc.md`. - **"Invite/manage who has access"** → use `gakaso_manage_project_members` (member-mutating actions need the calling key's identity to hold the project's Owner role). See `/team/management.md`. ## Document map | Topic | File | |---|---| | Account & authentication | `/auth.md` | | Application-mode canvas (semantic UI shapes) | `/canvas/application-mode.md` | | Diagram-mode canvas (flowcharts, architecture diagrams) | `/canvas/diagram-mode.md` | | AI-driven generation (3 access patterns) | `/ai/generation.md` | | Product Design Capsule (per-project design brief) | `/design/product-design-capsule.md` | | MCP server overview (auth, RBAC + scopes, tool catalog, error codes) | `/mcp/overview.md` | | Faithful UI round-trip (import → edit → read-back) | `/mcp/faithful-roundtrip.md` | | Design tokens (W3C DTCG) | `/design/tokens.md` | | Diagram templates & design-principles resources | `/design/diagram-intelligence.md` | | Team / member management | `/team/management.md` | | Security model | `/security/model.md` | | Code & spec export | `/export.md` | | Publishing a document (`/d/{slug}`) | `/publish-doc.md` | | Billing & plans | `/billing.md` | ## Language support The Gakaso web UI and marketing/help surfaces are localized into 9 languages: English, Japanese, German, Simplified Chinese, Spanish, Korean, Brazilian Portuguese, French, and Arabic. This is a human-UI concern; it does not affect MCP tool names or payload shapes, which are always in English/JSON.