update-docs

What this skill does

**System Objective:** You are an expert technical writer and software architect. Your goal is to generate comprehensive, highly structured documentation for this codebase. Instead of creating a separate documentation folder, you will create a `CONTEXT.md` file directly inside every valid source directory within the project. You must read and analyze the actual contents of the files to generate deep, contextual `CONTEXT.md` files that explain what the code does, how services interact, and the overall architecture.

**Strict In-Context Execution:**
Do not write or execute secondary scripts (e.g., Python, Node.js) to call the Gemini API or automate this task. You must use your built-in tools to read the file contents directly into our chat context, analyze the code yourself, and generate the `CONTEXT.md` files using your own capabilities.

**Scope & Constraints:**
- Create documentation directly in the existing source directories. Do not create a mirrored `docs/` folder.
- Strictly respect `.gitignore`. Do not document or open ignored directories (e.g., `node_modules`, `.venv`, `build`, `dist`, `.git`).
- Every non-ignored folder, including the project root, must have a corresponding `CONTEXT.md` file created inside it.

**Documentation Content Standards:**
Each `CONTEXT.md` must be concise but highly informative, including:
1. **Purpose:** A high-level summary of what the folder/module does.
2. **Detailed File Overviews:** Provide a detailed overview for each file based on your direct analysis of the code in our chat context. Explain its core logic, exposed methods, and specific role in the system. Do not guess based on the file name.
3. **Dependencies/Relationships:** How this folder interacts with other parts of the codebase.
4. **Usage/Exports:** What core functions, classes, or services are exposed here.

**Execution Strategy (Bottom-Up Aggregation):**
Execute this task strictly in the following sequential order:
1. **Map the Tree:** Generate a recursive list of all valid, non-ignored directories.
2. **Leaf Nodes First (Deep Analysis):** Begin with the deepest sub-directories (leaf nodes). 
    - Use your built-in tools to open and read the contents of the files in the directory.
    - Generate a `CONTEXT.md` file directly in that folder, using the knowledge gained from reading the code to write the detailed overviews.
3. **Ascend & Aggregate:** Move up one directory level. To write the parent folder's `CONTEXT.md`, read the contents of its direct files AND synthesize the context from the sub-folder `CONTEXT.md` files you just created. 
4. **The Root CONTEXT.md:** Continue this bottom-up process until you reach the project root. Generate the final `CONTEXT.md` in the root directory. This top-level document must synthesize all aggregated context to provide a clear, overarching view of the application's architecture, services, and tech stack.

Begin by confirming you understand the instructions and outputting the mapped directory tree. Then, proceed with step 2.

**Helper Scripts:**
To assist with mapping directories and verifying the documentation completeness, you can use the built-in bash scripts from the `.agents/skills/update-docs/scripts/` folder:

1. **Get Directories**: Run `get_directories.sh` (from the project root or any directory) to recursively list all valid, trackable directories, excluding completely ignored paths like `.git`, `node_modules`, and `.agents`.
   ```bash
   ./get_directories.sh
   ```
   Pass the `--missing` flag to only list directories that do not yet have a `CONTEXT.md` file:
   ```bash
   ./get_directories.sh --missing
   ```
   Pass the `--stale` flag to list directories where the `CONTEXT.md` file is older than other files in that directory or its subdirectories:
   ```bash
   ./get_directories.sh --stale
   ```

2. **Check Missing Context**: Run `check_missing_context.sh` to get a report of any valid directories that are missing a `CONTEXT.md` file. It will output all paths missing the file, and return an error if omissions exist.
   ```bash
   ./check_missing_context.sh
   ```

3. **Clean Docs**: Run `clean_docs.sh` to recursively delete all `CONTEXT.md` files from valid project directories.
   ```bash
   ./clean_docs.sh
   ```