# CamMonitor

## Overview

CamMonitor is a self-hosted security camera footage viewer. It provides the Go HTTP server, a `/health` endpoint, environment-based configuration, SQLite startup and migrations, bcrypt login, session cookies, admin user management, an in-memory footage index, and Docker Compose deployment.

## Getting Started

Copy the sample environment file and adjust it for your footage directory:

```bash
cp .env.example .env
```

Start the app with Docker Compose:

```bash
docker compose up --build
```

Verify the server is running:

```bash
curl http://localhost:8080/health
```

The response should be:

```json
{"status":"ok"}
```

Open `http://localhost:8080/login` and sign in with `ADMIN_USER` and `ADMIN_PASS`. On the first run, CamMonitor creates that bootstrap admin account only when the user table is empty. After login, admins can add or delete users at `/admin/users`.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Host port published by Docker Compose |
| `LISTEN_ADDR` | `:8080` | TCP address used by the Go server |
| `FOOTAGE_ROOT` | `/footage` | Camera footage directory inside the container |
| `DB_PATH` | `/data/cammonitor.db` | SQLite database path |
| `ADMIN_USER` | `admin` | Bootstrap admin username created on first run when no users exist |
| `ADMIN_PASS` | `changeme` | Bootstrap admin password created on first run when no users exist |
| `SESSION_TTL` | `24h` | Session cookie lifetime |
| `SCAN_INTERVAL` | `5m` | Footage rescan interval |

## Authentication

All app routes except `/health`, `/login`, and `POST /login` require a valid `session` cookie. Unauthenticated requests are redirected to `/login`. Admin-only pages return `403 Forbidden` for signed-in non-admin users.

The login form posts credentials to `/login`. Successful login sets an HTTP-only `session` cookie and redirects to `/`; invalid credentials return `401 Unauthorized`. `POST /logout` deletes the server-side session, clears the cookie, and redirects back to `/login`.

Admin users can manage accounts at `/admin/users`. New users are created with bcrypt-hashed passwords, and deleting a user also removes their sessions through the SQLite foreign key cascade.

## Footage Layout

Footage is mounted read-only at `/footage` in the container. CamMonitor scans this tree on startup and then rescans it on the `SCAN_INTERVAL` schedule. Days are indexed from `YYYYMMDD` directories, with images and videos sorted chronologically inside each day.

The expected directory format is:

```text
YYYYMMDD/
  images/
    AYYMMDDHHMMSSNN.jpg
  record/
    AYYMMDD_HHMMSS_HHMMSS.265
```

## AI Workflow

This project includes the persistent planner/implementer/reviewer workflow with file-based coordination, plus the PO orchestration layer.
Manual and auto are two runtime modes for the same scaffold: they use the same generated files, task board, and review gate. Fewer role sessions means less coordination overhead and lower token cost.

## Modes

This scaffold supports two workflow profiles that share the same generated files, task board, plan, review log, and handoff log.

- `full` keeps the planner, implementer, reviewer, and optional PO split.
- `lite` keeps the planner but replaces separate implementer/reviewer sessions with one `aide dev` session.

| Profile | Sessions and launchers | Who drives work | Commit cadence | PO support | Recommended fit |
|---------|------------------------|-----------------|----------------|------------|-----------------|
| `full` | `aide plan`, `aide implement`, `aide review`, optional `aide po` | Separate role sessions with explicit implement/review handoffs | One final task commit after reviewer approval | yes | Larger, riskier, or more review-heavy changes |
| `lite` | `aide plan`, `aide dev` | Planner plus one dev session that implements and reviews, then halts for human approval at `ready_for_review` | One real commit per task, including `all_task` | no | Smaller changes or lower-coordination work |

### How to switch

```bash
aide profile full
aide profile lite
```

Use `aide profile full` to return to the split workflow, or `aide profile lite` to switch to the dev-session flow.

`full` is the default for new scaffolds. When you switch to `lite`, `aide implement`, `aide review`, and `aide po` refuse and point you at `aide dev`. When you switch back to `full`, `aide dev` refuses and points you at `aide implement` and `aide review`.

### Runtime modes

- Manual mode: start the planner, implementer, and reviewer in separate terminals, then drive each session yourself with the documented text commands.
- Auto mode: run `aide po` to start the PO session, which uses MCP tools to coordinate the post-planning implementer/reviewer workflow for you.

### Concepts

**Cycle** — a unit of work on a feature branch. One cycle = one branch = one PR.

**Roles and file ownership:**

| Role | Reads | Writes |
|------|-------|--------|
| PO | `.ai/TASKS.md`, `.ai/PLAN.md`, `.ai/REVIEW.md`, `.ai/prompts/po.md` | MCP session commands via `aide po` |
| Planner | `ROADMAP.md` | `.ai/PLAN.md`, `.ai/TASKS.md` |
| Implementer | `.ai/PLAN.md`, `.ai/REVIEW.md` | source code, `.ai/TASKS.md` |
| Reviewer | `.ai/PLAN.md`, commits | `.ai/REVIEW.md`, `.ai/TASKS.md` |

**Status flow:**

```text
in_planning → ready_for_implement → in_implementation → ready_for_review → in_review → ready_to_commit → done
                                          ↑                                     |
                                          └──── changes_requested ◄─────────────┘
```

### Start a new development cycle

```bash
# Edit ROADMAP.md with your goals first, then:
aide cycle start feature/<scope>
```

### Full profile quick start

```bash
aide plan          # terminal 1
aide implement     # terminal 2
aide review        # terminal 3
```

Launch each role once, then keep those sessions open for the rest of the cycle.

Role launchers read default agent/model settings from `.ai/config.json`.
To override, pass the agent first, then any CLI flags.
Example: `aide review claude --model sonnet`
Claude starts interactively by default, and the Codex launcher uses interactive `codex` mode so the session stays open for role commands.

### Lite profile quick start

```bash
aide profile lite
aide plan          # terminal 1
aide dev           # terminal 2
```

The dev session handles implementation and review, then halts for human approval at `ready_for_review`. In lite mode, `aide implement`, `aide review`, and `aide po` refuse and point you at `aide dev`.

### Start the PO orchestrator (auto mode)

```bash
aide po
```

The PO session drives the post-planning task board flow through the `aide` MCP server. PO orchestration is available only in the `full` profile.
By default, `aide po` launches Claude with `--model haiku`, and `aide po codex` launches Codex with `-m gpt-5.4-mini`. `.ai/config.json` can override those defaults, and an explicit CLI `--model` or `-m` flag takes precedence.
If no tasks are in `ready_for_implement` or later, run the planner first.
The normal MCP completion path is `session_run` followed by `session_wait`, then a re-read of `.ai/TASKS.md`; `session_get_output` is for debugging only.
The MCP server appends structured debug logs to `.ai/mcp-server.log`, and the scaffold gitignore excludes that file.

### Drive work inside the existing sessions

```text
planner> start_plan
implementer> next_task T-001
reviewer> next_task T-001
implementer> commit_task T-001
dev> next_task T-001
dev> commit_task T-001
implementer> rework_task T-001
aide cycle end 0.7.0
```

Cross-platform CLI equivalents:
`aide cycle end [VERSION]` closes the cycle outside the persistent role session, and `aide pr [--dry-run]` creates or updates the branch PR.

**Planner commands:**

Before `start_plan`, freeform conversation with the planner is the roadmap-refinement phase. Use it to sharpen scope, acceptance criteria, constraints, and trade-offs directly in `ROADMAP.md`. `start_plan` is the explicit handoff into formal planning.

| Command | Description |
|---------|-------------|
| `start_plan` | Read `ROADMAP.md`, write `.ai/PLAN.md` and `.ai/TASKS.md` |
| `rework_plan [TASK_ID]` | Revisit the plan when scope or approach changes |

**Implementer commands:**

| Command | Description |
|---------|-------------|
| `next_task [TASK_ID]` | Pick up the next `ready_for_implement` task |
| `commit_task [TASK_ID]` | Turn a `ready_to_commit` task into one clean final commit, including task-specific `.ai/` artifacts |
| `rework_task [TASK_ID]` | Address `changes_requested` findings from `.ai/REVIEW.md` |
| `aide cycle end [VERSION]` | Close the cycle after all tasks reach `done`, committing remaining `.ai/` artifacts with a `Release-As:` footer |
| `status_cycle [TASK_ID]` | Show task status and recommended next action |

**Reviewer commands:**

| Command | Description |
|---------|-------------|
| `next_task [TASK_ID]` | Pick up the next `ready_for_review` task and run review plus verification |
| `status_cycle [TASK_ID]` | Show task status and recommended next action |

### File map

| File | Purpose | Tracked |
|------|---------|---------|
| `.ai/PLAN.md` | Current plan | yes |
| `.ai/TASKS.md` | Task board with status | yes |
| `.ai/prompts/po.md` | PO orchestration prompt for auto mode | yes |
| `.ai/REVIEW.md` | Review findings | yes (tracked cycle log) |
| `.ai/HANDOFF.md` | Runtime handoff log | yes (tracked cycle log) |
| `.ai/config.json` | Per-role launch defaults | yes |
| `ROADMAP.md` | Cycle goals (edit before planning) | yes |
| `AGENTS.md` | Project-specific and workflow-managed agent rules | yes |
| `CLAUDE.md` | Agent instruction entry point (`@AGENTS.md`) | yes |
| `aide po` | Launch the PO orchestration session | yes |

### Create a PR

```bash
aide pr
```

Full workflow details and session recovery rules are in `AGENTS.md`.