This guide helps maintainers find the right code path before changing Gentle-AI. It is an index, not a full API reference.
| Reader | Use this guide to |
|---|---|
| New maintainer | Build the project mental model before touching files. |
| Contributor | Find the package that owns a behavior. |
| Reviewer | Check whether a PR changes the right layer. |
| Release helper | Verify sync, install, update, and docs boundaries. |
Gentle-AI is a Go CLI/TUI that configures AI coding agents. It installs and syncs managed assets such as SDD prompts, skills, MCP entries, permissions, personas, GGA support, and Engram wiring.
User
|
v
gentle-ai CLI / Bubbletea TUI
|
+--> detection + flag normalization
+--> planner resolves components and dependencies
+--> pipeline applies adapter/component steps with backups
+--> verification reports readiness
|
v
Agent config roots (~/.claude, ~/.config/opencode, ~/.cursor, ...)
|
v
External tools and agents: Engram, Context7, GGA, supported AI CLIs/IDEs
Golden rule: agent-specific paths belong in adapters; reusable behavior belongs in components or shared orchestration packages.
| Page | Job |
|---|---|
| Mental model | Understand what the project is, is not, and must preserve. |
| Repository map | Find package ownership and placement rules. |
| Memory core | Understand the Engram boundary and what this repo wires vs owns. |
| Interfaces | Compare CLI, MCP, local HTTP API boundary, and TUI surfaces. |
| Sync and cloud | Separate Gentle-AI config sync from Engram memory/cloud sync. |
| Dashboard | Know what dashboard code is absent from this repo and how to avoid inventing it. |
| Integrations | Change agent adapters, plugins, and setup boundaries safely. |
| Maintainer playbook | Use checklists by change type and PR review guardrails. |
| Reference map | Trace docs and source files to responsibilities. |
- Start with Mental model.
- Use Repository map before editing code.
- Read Interfaces for user-facing changes.
- Read the specialized page for your area: memory, sync, dashboard, or integrations.
- Finish with Maintainer playbook before opening or reviewing a PR.
- Architecture & Development — short codebase layout and test commands.
- Usage — user-facing CLI/TUI behavior.
- Engram Commands — Engram user commands and MCP tool overview.
- OpenCode SDD Profiles — profile sync details.
- Agents — supported agent matrix and config paths.
Read Mental model next.