# Project Initialization

The `/init` command analyzes your codebase and generates documentation that LogiCoal uses as project context in every conversation.

## What It Does

1. **Scans your project** — Detects languages, frameworks, directory structure, and key files  
2. **Detects frameworks** — Recognizes 25+ frameworks including Laravel, Django, Next.js, Nuxt, SvelteKit, Astro, Remix, Angular, Electron, React Native, Prisma, Supabase, and more  
3. **Generates `.COAL.md`** — AI-powered project documentation covering architecture, components, setup, and conventions  
4. **Scaffolds `.coals/`** — Creates a workspace directory for plans, research, artifacts, and agent files

## Usage

From inside the LogiCoal chat (generates `.COAL.md` via AI + scaffolds `.coals/`):

```
/init
/init --force     ← overwrite existing .COAL.md
```

From the shell (scaffolds `.coals/` only — does not generate `.COAL.md`):

```bash
logicoal init
logicoal init --force
```

## Generated Files

### `.COAL.md`

An AI-generated project overview with 7 sections:

1. **Overview** — What the project is and does  
2. **Architecture** — High-level design and patterns  
3. **Project Structure** — Key directories and their purposes  
4. **Key Components** — Important modules and their relationships  
5. **Development** — Prerequisites, install, dev, build, and test commands  
6. **Code Style & Conventions** — Naming, formatting, and patterns used in the project  
7. **Important Notes** — Configuration, environment variables, gotchas

LogiCoal reads `.COAL.md` automatically at the start of every session, giving the AI immediate context about your project. You don't need to explain your project structure each time.

### `.coals/` Directory

```
.coals/
├── plans/        ← Implementation plans and architectural decisions
├── research/     ← Research notes and findings
├── artifacts/    ← Generated code snippets and configurations
├── prompts/      ← Saved prompts and templates
├── progress/     ← Progress tracking and session summaries
├── README.md     ← Auto-generated directory explanation
└── .gitignore    ← Ignores temp and log files
```

You can also create these directories manually for additional project-level configuration:

- `.coals/agents/` — Project-local custom agent roles (`.md` files). See [Custom Roles](/content/docs/custom-roles/index.html).
- `.coals/mcp.json` — Project-local MCP server configuration. Created by `/mcp add`. See [MCP Integration](/content/docs/mcp/index.html).

This directory is designed to be committed to version control so your team shares the same project context.

## Tips

- Run `/init` once when you start using LogiCoal with a project  
- Use `/init --force` to regenerate after major architectural changes  
- Edit `.COAL.md` manually if the AI missed something important — it's just markdown  
- Agent plans are saved to `.agents/plan/` in your project root (not inside `.coals/`). You can use `.coals/` subdirectories for your own research, artifacts, and progress tracking