From f3ad78f2637b0dfaa7167928d2a51b8a1269e94b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kris=20Kr=C3=BCg?= Date: Sun, 28 Jun 2026 13:10:42 -0700 Subject: [PATCH] docs: spektorAI canonical front door, rename WhisperForge handbook, keep source-available Resolve the spektorAI/WhisperForge naming split and the README case collision before publishing the house-style front-door docs. - name: spektorAI is the public/project name; WhisperForge stays the engine (whisperforge_core, the services, the handbook). project.yaml name follows. - readme.md -> WHISPERFORGE.md (git mv, history + links preserved): the detailed engine handbook. kills the case-insensitive README.md clash and keeps long-form docs at root, matching ROADMAP/STATUS/changelog. - add house-style README.md (front door), AGENTS.md, llms.txt in KK voice. - license unchanged: no OSS license granted, source-available only, no MIT. - repoint docs_truth_check.py + docs-truth.yml at README.md/WHISPERFORGE.md; make docs-check passes (18 docs, 15 targets). Pre-existing local WIP (ROADMAP, STATUS, services, tests, ui, whisperforge_core) deliberately left unstaged. Co-Authored-By: Claude Opus 4.8 --- .company-os/project.yaml | 2 +- .github/workflows/docs-truth.yml | 3 +- AGENTS.md | 17 +++++++++++ README.md | 48 ++++++++++++++++++++++++++++++++ readme.md => WHISPERFORGE.md | 0 llms.txt | 20 +++++++++++++ scripts/docs_truth_check.py | 3 +- 7 files changed, 90 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md create mode 100644 README.md rename readme.md => WHISPERFORGE.md (100%) create mode 100644 llms.txt diff --git a/.company-os/project.yaml b/.company-os/project.yaml index 0095345..f05223c 100644 --- a/.company-os/project.yaml +++ b/.company-os/project.yaml @@ -1,6 +1,6 @@ project: id: "spektorai" - name: "WhisperForge" + name: "spektorAI" type: "repo" owner: "kk" production_surface: "local-first Streamlit voice-to-knowledge workbench; hosted service mode is optional" diff --git a/.github/workflows/docs-truth.yml b/.github/workflows/docs-truth.yml index f854420..707c00e 100644 --- a/.github/workflows/docs-truth.yml +++ b/.github/workflows/docs-truth.yml @@ -4,7 +4,8 @@ on: pull_request: paths: - "Makefile" - - "readme.md" + - "README.md" + - "WHISPERFORGE.md" - "STATUS.md" - "ROADMAP.md" - "changelog.md" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e4d5f37 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# AGENTS.md + +How to work in this repo, for humans and their agents. + +## what this is +spektorAI is the home of WhisperForge, a local-first Streamlit voice-to-knowledge workbench: audio or dictation in, source-grounded draft + social + Notion page out. + +## ground rules +- match the existing style. surgical changes only. +- public copy follows the house voice: see kk-brand/VOICE.md. full punk, no em dashes. +- business logic lives in `whisperforge_core/`. UI and CSS live in `ui/` and `styles.py`. `app.py` is just the composition root. +- the Makefile is the command surface. `make app` runs it, `make test` runs the suite, `make smoke` boots the shell and hits health, `make docs-check` checks doc truth. +- routing stays dry-run by default. handoffs to GitHub/Linear/Notion, paid-provider swaps, deploys, and external sends need explicit human approval. do not flip those on your own. +- no open-source license is granted. treat the code as source-available for collaboration, not freely redistributable. + +## the maker +Kris Krüg (@WalksWithASwagger) · https://kriskrug.co · BC + AI diff --git a/README.md b/README.md new file mode 100644 index 0000000..f308692 --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +```text +K R Ü G ·· spektorAI +the future belongs to the weird +``` + +# spektorAI + +`talk your thoughts. get back a draft in your voice, with receipts.` + +spektorAI is the home of WhisperForge, the voice-to-knowledge workbench I use to turn spoken thoughts into publishable work without losing my own voice. I dictate or upload audio, it transcribes, pulls the wisdom, drafts an article, writes the social posts and image prompts, and ships the whole bundle to a structured Notion page. it runs local-first as a Streamlit app on my machine. the voice comes from a per-user prompt and knowledge base, so the output sounds like me and not like a content mill. + +it is built for people who think out loud and hate doing the same cleanup-and-formatting grind twice. it is not a hosted SaaS. you run it from a checkout, your keys stay where you put them, and nothing leaves the machine unless you send it somewhere on purpose. + +## what it does + +- take a Wispr Flow dictation, a pasted note, an upload, or a live browser recording, and turn it into one durable capture +- transcribe locally on Apple Silicon, on CPU, or in the cloud · your call, your tradeoff +- run the pipeline: clean the transcript, pull chapters and wisdom, draft an outline, write the article, spin up social posts and image prompts +- draft, critique, revise. a fact-check pass flags claims the transcript does not actually back up +- write in your voice via prompts + a knowledge base under `prompts//`, injected on every call +- review a draft next to its source receipts before anything ships. advisory scorecards, no gatekeeping +- hand off a capture or output as a GitHub or Linear issue draft. routing stays dry-run until you approve it +- ship a clean, color-coded Notion page with title, tags, summary, and run metrics +- pick your writing engine: OpenAI, Anthropic, or local Ollama. default is Claude Haiku 4.5, fast and cheap and in your voice + +## start here + +needs Python 3.10+ and `ffmpeg` on your PATH (`brew install ffmpeg` on macOS). + +```bash +git clone https://github.com/WalksWithASwagger/spektorAI.git +cd spektorAI +python3 -m venv venv && source venv/bin/activate +pip install -r requirements.txt +cp .env.example .env # add OPENAI_API_KEY + NOTION keys, ANTHROPIC_API_KEY recommended +make app # → http://localhost:8501 +``` + +full setup, the provider matrix, and the run-recovery flow live in the engine handbook, [`WHISPERFORGE.md`](WHISPERFORGE.md). roadmap: `ROADMAP.md`. current handoff state: `STATUS.md`. + +## these repos run on agents + +built to be operated by humans and machines. see `AGENTS.md` and `llms.txt`. + +--- +> i don't build systems that optimize humans. i craft spaces where humans can be gloriously inefficient, creative, and alive. + +made by Kris Krüg · [@WalksWithASwagger](https://github.com/WalksWithASwagger) · [kriskrug.co](https://kriskrug.co) diff --git a/readme.md b/WHISPERFORGE.md similarity index 100% rename from readme.md rename to WHISPERFORGE.md diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..61cbd56 --- /dev/null +++ b/llms.txt @@ -0,0 +1,20 @@ +# spektorAI + +> WhisperForge: a local-first voice-to-knowledge workbench. talk or upload audio, get back a transcript, extracted wisdom, an article, social posts, and image prompts in your own voice, shipped to a structured Notion page. + +spektorAI is the canonical home of WhisperForge, a Streamlit app that runs on your own machine. Wispr Flow dictations, pasted notes, uploads, and browser recordings become durable captures, run through a draft-critique-revise pipeline with a source-grounded fact-check, and export to Notion, Markdown, or a GitHub/Linear handoff draft. voice comes from per-user prompts + a knowledge base. Python. built by Kris Krüg / BC + AI. + +License posture: no open-source license is currently granted. source-available for project collaboration only. do not treat the archived WalksWithASwagger/whisperforge MIT license as inherited. + +## Key files +- [README](README.md): what spektorAI is, what WhisperForge does, and the one command that proves it +- [AGENTS.md](AGENTS.md): how agents should operate in this repo +- [WHISPERFORGE.md](WHISPERFORGE.md): detailed WhisperForge engine docs (features, architecture, setup, env reference) +- [ROADMAP.md](ROADMAP.md): stabilization and product direction +- [STATUS.md](STATUS.md): current handoff state +- [changelog.md](changelog.md): release history + +## Links +- Author: Kris Krüg · https://kriskrug.co +- Community: BC + AI · https://bc-ai.ca +- Repo: https://github.com/WalksWithASwagger/spektorAI diff --git a/scripts/docs_truth_check.py b/scripts/docs_truth_check.py index 8ea7b6f..4240580 100644 --- a/scripts/docs_truth_check.py +++ b/scripts/docs_truth_check.py @@ -10,7 +10,8 @@ PROJECT_DOCS = ( - "readme.md", + "README.md", + "WHISPERFORGE.md", "STATUS.md", "ROADMAP.md", "changelog.md",