diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index 802b843..6989c3b 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -190,9 +190,9 @@ This is genuinely useful once the system is running. It makes working with Claud **macOS:** [SuperWhisper](https://superwhisper.com) with a local Parakeet model runs via WhisperKit on the Apple Neural Engine. Audio is processed entirely on-device. System-wide hotkey, inserts into any focused app. Free tier works well. This is the most turnkey option on Mac. Built-in Apple Dictation is a reasonable fallback if you want zero setup. -**Windows:** [OmniDictate](https://github.com/Turbo-Adib/OmniDictate) — free, open-source, uses faster-whisper as the backend. Push-to-talk via Right Shift (configurable), types directly into any focused Windows application. NVIDIA GPU with CUDA gives best performance; CPU-only mode works but is slower on larger models. Available as a `.exe` installer from the Releases page. Actively maintained — v2.0 shipped December 2025. Windows SmartScreen will warn on first run (unsigned binary); click through. +**Windows:** [OmniDictate](https://github.com/gurjar1/OmniDictate) — free, open-source, uses faster-whisper as the backend. Push-to-talk via Right Shift (configurable), types directly into any focused Windows application. NVIDIA GPU with CUDA gives best performance; CPU-only mode works but is slower on larger models. Available as a `.exe` installer from the Releases page. Actively maintained — v2.0 shipped December 2025. Windows SmartScreen will warn on first run (unsigned binary); click through. -**Linux:** [WhisperTux](https://github.com/medmunds/whispertux) — free, open-source, uses whisper.cpp as the backend. Global keyboard shortcut for start/stop, auto-injects text into the focused application. Works without a GPU — whisper.cpp runs on plain x86 with AVX. GPU acceleration supported if available. Works on GNOME and KDE. Install via `git clone` + `python3 setup.py` which handles dependencies, model download, and service registration. Last commit February 2026. +**Linux:** [WhisperTux](https://github.com/cjams/whispertux) — free, open-source, uses whisper.cpp as the backend. Global keyboard shortcut for start/stop, auto-injects text into the focused application. Works without a GPU — whisper.cpp runs on plain x86 with AVX. GPU acceleration supported if available. Works on GNOME and KDE. Install via `git clone` + `python3 setup.py` which handles dependencies, model download, and service registration. One practical note: voice dictation produces transcription artefacts — misheard words, missing punctuation, run-on sentences. Claude handles this well if you prompt it naturally. You do not need to clean up every word before submitting. @@ -235,8 +235,8 @@ Once the baseline is stable, these are natural next layers — each independent, | Layer | What it adds | Requires | |---|---|---| | Private Git hosting | Self-hosted Forgejo instead of GitHub | A VPS or home server | -| Infrastructure monitoring | Prometheus + Grafana + Alertmanager | A VPS | -| Log aggregation | Loki + Grafana Alloy | A VPS | +| Infrastructure monitoring | Prometheus + Grafana + Alertmanager | Any always-on machine — local to learn, VPS for reliability | +| Log aggregation | Loki + Grafana Alloy | Any always-on machine | | Secure remote access | WireGuard VPN | A VPS | | Local AI inference | Ollama + Open WebUI | GPU with adequate VRAM | | Multi-agent workers | Codex + Gemini alongside Claude | Existing workspace | @@ -312,19 +312,55 @@ how they hand off work, and what prevents them from conflicting. --- -## Files to Create in Your Own Repo +## Bootstrap Your Repo with Claude -These are the documents that make an AI-assisted repo work well. None of them are magic — they are just Markdown files with clear purposes. Build them gradually as you need them. +Once the baseline is running, use these prompts to build the foundation documents. Each one is a single conversation — paste the prompt, answer Claude's questions, and commit the result. -| File | Purpose | Create it when… | -|---|---|---| -| `README.md` | Human-facing landing page — what this is, current state, key links | Day one | -| `ENTRYPOINT.md` | Agent session startup — what to read first, environment facts, execution boundaries | Once you have more than one doc | -| `AGENTS.md` | Operating contract for AI agents — what they can do, what requires approval | Before doing serious work with agents | -| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | When you have infrastructure to track | -| `docs/open-loops.md` | Persistent backlog across sessions — so nothing falls through the cracks | When unresolved items start accumulating | -| `bootstrap.sh` | Idempotent setup script — verifies the workspace is in the expected state after rebuilds | Once your setup has more than 3 steps | -| `.claude/rules/` | Repo-level rules loaded every Claude session — safety, style, workflow | When you have patterns you keep repeating | -| `docs/vendor-docs/` | Current third-party documentation fetched and stored locally | Before writing any code that uses an external library | +**Create your session entrypoint document:** +``` +I am setting up a Git repo as a control plane for AI-assisted development. -**The most important habit:** Ask Claude to fetch current docs before writing any code that uses a third-party library, API, or tool. Training data is frozen. The docs are not. +Create an ENTRYPOINT.md for this repo that: +- Lists the key documents an AI agent should read before starting work +- States what this repo is and what it is for +- States the execution boundaries (what runs in the container vs what runs on the host) +- States where secrets are kept and that they must never enter the repo + +Ask me questions about my setup before writing anything. +``` + +**Create your agent operating contract:** +``` +Create an AGENTS.md for this repo that defines: +- What AI agents are permitted to do autonomously +- What requires explicit human approval before proceeding +- The Git branch model (who works on which branch) +- What agents must never do (commit secrets, push to main directly, etc.) + +Ask me about my setup and which agents I am using before writing anything. +``` + +**Create your open loops document:** +``` +Create a docs/open-loops.md for this repo. + +This file tracks unresolved items across sessions — things that are in progress, +decisions that have not been made, or work that is blocked. It should be read at +the start of every session so nothing falls through the cracks between conversations. + +Start it with the current open items from our conversation so far. +``` + +**Scaffold the full foundation in one pass:** +``` +I have a new Git repo for AI-assisted development. I need you to create the +following foundation documents, asking me questions before writing each one: + +1. README.md — what this repo is, current state, key links +2. ENTRYPOINT.md — agent session startup, read order, execution boundaries +3. AGENTS.md — what agents can and cannot do, branch model +4. docs/open-loops.md — persistent backlog of unresolved items + +For each document: ask me the questions you need answered, write a first draft, +show it to me, and wait for approval before moving to the next one. +```