Handbook

Clean Local Tools Handbook

This directory is the durable human-and-AI-readable handbook for Clean Local Tools.

If you are a future maintainer, contributor, automated coding agent, or AI assistant with no prior project context, start here. Do not assume undocumented knowledge from previous conversations.

What this project is

Clean Local Tools is a collection of useful browser-based tools designed around a simple idea: people should be able to perform everyday digital tasks without unnecessarily surrendering their files, personal information, or attention.

Master promise: Your files never leave your machine.

The intended product direction is private, local-first software that runs primarily in the user's browser. The project deliberately avoids a business model based on harvesting user data or filling utilities with advertising.

Reading order

Coding agents should also read the root AGENTS.md. Approved app specifications use docs/04-workflow/jules-task-brief.md as their issue template.

Documentation rules

These documents are part of the system, not promotional copy.

Write for a capable person who has never seen the repository before.
Also write so an AI coding agent can recover intent, constraints, architecture, and verification steps without relying on chat history.
Explain why important decisions exist, not only what the code currently does.
Clearly distinguish current behavior, architectural direction, and future ideas.
Never claim a privacy, offline, security, browser-compatibility, or test guarantee that the implementation does not actually prove.
Keep commands, paths, routes, interfaces, and invariants explicit.
Update documentation in the same change when architecture or operating assumptions change.
Record significant architectural choices as Architecture Decision Records (ADRs).
Prefer plain language first. Add technical detail where it helps a maintainer reproduce or verify the behavior.

Published HTML

Pages with render: true are compiled by scripts/build-docs.js; generated HTML must not be edited directly. Markdown remains the content source of truth.

layout: brand is reserved for public, indexable storytelling pages. A supported variant, headline, and heroCopy are required so the compiler can create the appropriate hero, section composition, navigation state, and closing action.
The default document layout is for technical handbook pages. These pages remain readable, restrained, and noindex unless a deliberate publishing decision changes that boundary.
assets/site.css contains the shared homepage and documentation shell. assets/docs.css contains brand-page and technical-document composition.
Generated pages and the homepage use content-hashed stylesheet URLs so a deployment cannot leave visitors on stale presentation code.

Source of truth

The repository and its automated tests are the executable source of truth. This handbook explains intent and operation. If documentation and code disagree, investigate the discrepancy rather than silently assuming either one is correct.

The permanent known-green historical reference branch is baseline/clean-local-tools-ci-v1. It must not be moved unless the project owner explicitly decides to redefine that baseline.

Current architecture in one sentence

Clean Local Tools is a static Astro-built site hosted on GitHub Pages. Existing tool routes continue to use browser HTML/CSS/JavaScript during the incremental migration; user-file processing remains in the browser. Automated quality gates cover static invariants plus Chromium, desktop WebKit, and mobile WebKit workflows.

Local AI is an experimental architectural direction. Its reference implementation and physical-hardware evidence remain isolated from production on test/webgpu-hardware-preview-v1 until the capability is ready for a separate promotion decision.

Stewardship

The project is intended to outlive any single maintainer, including its founder. No essential operating knowledge should exist only in one person's memory, laptop, private notes, or AI conversation history.