docs/CLAUDE.md

ClearGrow Documentation

Documentation for the ClearGrow IoT agricultural monitoring system.

Verify loaded: "ClearGrow Documentation Assistant ready."

Quick Start

Start a documentation management session:

/docs

Or use the librarian subagent directly for documentation tasks.

Documentation Structure

docs/
├── guides/                    # Learning & Doing
│   ├── user/                  # End-user documentation
│   │   ├── getting-started/   # Unboxing, first run, pairing
│   │   ├── daily-use/         # Dashboard, zones, alerts
│   │   ├── maintenance/       # Firmware updates, battery
│   │   └── troubleshooting/   # Common issues, support
│   └── developer/             # Developer documentation
│       ├── onboarding/        # Toolchain, first build
│       ├── contributing/      # Code style, pull requests
│       └── testing/           # Unit tests, simulator
├── reference/                 # Looking Up (specifications)
│   ├── architecture/          # System design
│   │   ├── controller/        # Task architecture, memory
│   │   ├── networking/        # Thread, WiFi, messages
│   │   └── probe/             # Probe architecture
│   ├── api/                   # Protocol specifications
│   │   └── internal/          # Component APIs
│   ├── firmware/              # Component specs
│   │   ├── controller/        # WiFi, OTA, settings
│   │   └── probe/             # Sensors, resilience
│   ├── hardware/              # PCB, pinouts
│   ├── ui/                    # Screens, styles
│   └── errors/                # Error codes
└── project/                   # Internal Working Documents
    ├── tasks/                 # Active TASK_*.md files
    ├── roadmap/               # Future features
    ├── assessments/           # Code analysis
    ├── archive/               # Completed tasks
    └── decisions/             # ADRs

Categories

Guides (guides/)

Learning-oriented content for users and developers.

Path	Audience	Purpose
guides/user/	End users	Setup, daily use, troubleshooting
guides/developer/	Developers	Onboarding, contributing, testing

Reference (reference/)

Lookup-oriented specifications and API documentation.

Path	Contents
reference/architecture/	System design, component diagrams
reference/api/	REST, CoAP, MQTT, internal APIs
reference/firmware/	Component specifications
reference/hardware/	PCB, pinouts, manufacturing
reference/ui/	Screens, styles, components
reference/errors/	Error codes and recovery

Project (project/)

Internal working documents for development.

Path	Contents
project/tasks/	Active implementation tasks
project/roadmap/	Future features (not implemented)
project/assessments/	Code analysis findings
project/archive/	Completed tasks
project/decisions/	Architecture Decision Records

Key Index Files

File	Purpose
guides/index.md	Guides navigation
reference/index.md	Reference navigation
project/index.md	Project overview
project/tasks/index.md	Active tasks
project/assessments/ASSESSMENT_STATUS.md	Assessment progress

Source of Truth

Documentation should match these source files:

Topic	Source File
GPIO pins	/opt/repos/controller/main/pin_config.h
Task architecture	/opt/repos/controller/CLAUDE.md
Events	/opt/repos/controller/components/common/include/app_events.h
UI screens	/opt/repos/controller/components/ui/screens/
Screen manager	/opt/repos/controller/components/ui/src/cg_screen_mgr.c
Probe firmware	/opt/repos/probe/CLAUDE.md
Simulator	/opt/repos/simulator/CLAUDE.md

Documentation Guidelines

1. Format: GitHub-flavored Markdown
2. Frontmatter: Use YAML frontmatter with title
3. Links: Use relative paths for internal links
4. Tables: Use markdown tables for structured data
5. Code: Fenced code blocks with language specifiers
6. Updates: Update index files when adding docs

Task File Format

Active tasks use the TASK_*.md naming convention:

---
title: "Task Name"
status: "active"
created: "YYYY-MM-DD"
---

# Task Name

## Overview
Brief description of the task.

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

## Implementation
Details about implementation approach.

## Testing
How to verify the task is complete.

When complete, move to project/archive/ and update project/index.md.

Common Tasks

Health Check

• Scan for broken links
• Check for stale TASK_*.md files
• Compare docs vs code modification dates
• Find TODO/FIXME comments

Sync with Code

• Update API docs when signatures change
• Update hardware docs when pins change
• Update architecture docs when tasks change
• Update UI docs when screens change

Task Management

• Create new TASK_*.md files
• Move completed tasks to archive
• Update project/index.md