# webFileBrowser

## Overview

A lightweight, container-based file browser for named host folders mounted
read-only into a container. It provides login-gated root and folder browsing;
file downloads and streaming are added in a later phase.

## Getting Started

Docker is the only prerequisite for the scaffold.

1. Update [`config/roots.example.json`](config/roots.example.json) with each
   root's display name and its absolute path *inside the container*.
2. Mount the matching host folders at those paths. The included
   [`compose.yaml`](compose.yaml) maps `${MEDIA_DIR:-./example-files}` to
   `/mnt/media` as an example.
3. Start the service:

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

The server listens on `http://localhost:8080` and logs every configured root
at startup. `/login` is the only public application route; every other route
redirects to login until it has a valid server-side session.

## Root configuration

Set `WEB_FILE_BROWSER_ROOTS_FILE` to a JSON configuration file containing a
`roots` array. Each root has a human-readable `name` and an absolute `path`
inside the container:

```json
{
  "roots": [
    {"name": "Media", "path": "/mnt/media"},
    {"name": "Documents", "path": "/mnt/documents"}
  ]
}
```

Alternatively, set `WEB_FILE_BROWSER_ROOTS` to a JSON array of the same root
objects. This environment variable takes precedence over
`WEB_FILE_BROWSER_ROOTS_FILE`:

```bash
WEB_FILE_BROWSER_ROOTS='[{"name":"Media","path":"/mnt/media"}]' \
  docker compose up --build
```

Each configured container path must be supplied by a Docker volume mount. To
add or remove a root, update both the configuration and the container's volume
mounts, then restart the container. Roots are intentionally fixed at startup;
they cannot be changed from the application.

## Authentication and persistent data

The application stores users and server-side sessions in SQLite. By default,
the database is `/var/lib/webfilebrowser/webfilebrowser.db`; set
`WEB_FILE_BROWSER_DATABASE_PATH` to use another path. The Compose example
uses a named volume for this directory, so users and active sessions survive a
container restart.

On the first database initialization, webFileBrowser creates this temporary
administrator account:

```text
Email:    boss@zecevic-ninja.com
Password: Start1234!
```

That account must change its password immediately after the first successful
login. It cannot access browsing, download, streaming, or administration routes
until the new password differs from the temporary password. Sessions are stored
server-side, use a seven-day sliding expiry, and are invalidated on logout.

The session cookie is always `HttpOnly`, `Secure`, and `SameSite=Lax`.
Terminate TLS at a reverse proxy before exposing the service; browsers will not
send the secure cookie over plain HTTP.

## Browsing folders

After changing the temporary password, select a configured root from the home
page and enter folders by clicking their names. Breadcrumb links take you back
through the current path. Each directory view shows the item name, type, size,
and last-modified time; this interface is read-only.

Every requested folder is resolved against its configured root. Parent-path
traversal and symlinks that resolve outside that root are rejected, so a mounted
folder cannot be used to browse unrelated container paths.

Use the theme button in the page header to switch between light and dark modes.
The preference is stored in the browser's local storage and is restored on the
next visit from that browser.

## 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`.