Vrataski — Product Ideas

The concrete product / onboarding ideas for Vrataski-as-a-product, extracted from vrataski-vision.md (§6) so the vision doc stays a tight read. All of this is aspirational, much-later horizon work — none of it is committed, and it presupposes the pivot the vision doc describes. Read vrataski-vision.md for the why; this is the what it could become. Drafted 2026-06-13.

These are the concrete ideas developed in conversation for what Vrataski-as-a-product could be. All of it is aspirational; none is committed.

Onboarding that embodies the ethos

Onboarding is the highest-stakes surface, because it's the most demand-character-prone part of any product (progress bars, "steps left," coercive funnels) — and a product whose entire claim is human-at-the-center, inform-don't-demand must prove that on first contact. The medium has to be the message: the onboarding itself must be calm, abandonable, and resumable, or it betrays the thesis in the first five minutes — especially for a skeptic already braced for AI to be pushy. Mechanically, onboarding is the brainstorming pipeline pointed at the user themselves (the understanding phase, about them); the user learns the human-in-the-loop method by being walked through it. It is the first dogfood.

Progressive disclosure of understanding, not features

Most onboarding reveals buttons over time; Vrataski reveals mental models over time — what an LLM actually is (a raw starting point, not a finished answer), why the chatbots felt shallow — but only just-in-time, never front-loaded as a lecture. This is the actual cure for the "AI is dumb" grievance: the shallowness is partly not knowing it's raw material; you let the person feel that rather than telling them.

Calibration: a prompt bank for the unsure

A curated, situational library of good questions the agent can offer when the user doesn't know where to go — explicitly a fallback for the unsure, not the spine of the flow (if the person knows what they want, the bank is skipped), so it never degrades into a phone-tree funnel. Tag it on two axes — situation × where the user is in their understanding — so the same "stuck" moment gets a teaching-heavy question for a novice and a terse one for someone who's grown. The questions are authored seeds the agent adapts, not verbatim scripts (human-drafted-then-refined beats fully generated), and a well-chosen question does double duty: it unsticks and teaches the shape of what's possible.

The hand-written introduction

A short, authored "This is Vrataski. It is/does…" in the author's third-person voice — not the AI performing personhood (which AI-skeptics specifically recoil from, the same disgust as "AI that writes books / makes art"). It's authored rather than generated because the load-bearing first-impression framing is too important to leave to generation variance. The agent should be able to read the intro (not just display it) so its first prompt picks up cleanly, and so the intro doubles as the voice anchor the agent inherits.

The transparent, co-authored user model — "what the human learned"

A log of what the human learned (mirroring the system's existing "session lessons," which records what the collaboration learned). This is the dogfooding-to-de-black-box thesis pointed at the user: every person gets a readable artifact of their own growing understanding. Critically, it is transparent and co-authored, not a hidden profile — the inverse of the silent user-models that breed distrust. "Here is the whole notebook we keep together, in your words, and you can read all of it" is among the strongest trust moves available for a skeptical audience. Early on, this learning-state can be the user's "current plan" (their first project is learning to drive the thing); as they mature it cools into a background companion while real work takes the foreground — the same heat→cool, in-context→out-of-context gradient the system already uses.

The transparency window

Because everything is plain markdown on disk, a markdown viewer is automatically a complete window into the agent's inner workings — there is no hidden state a viewer can't reach. This makes the transparency claim true by construction, the sharp contrast with the chatbots' genuinely hidden state (weights, unseen prompts, un-auditable profiles). Kingdom.md (the self-hosted Laravel markdown viewer, its own FOSS project) is the natural reading room: point a "kingdom" at the agent's working directory and the window exists almost for free. The relationship should be compose, not fuse — Kingdom.md ships as the general viewer it's designed to be; Vrataski uses it. Design notes: the window stays read-only (the agent is the sole writer; corrections happen in conversation), and it needs altitude / curation — the learning log (written for the human) is the front door, with the deeper machinery available to anyone who digs but never dumped raw. A per-file "For Humans" header is the file-level version of the same legibility move (mirroring the existing "orientation for fresh-Claude" preamble, which is effectively a "For Agents" header), scoped to the human-facing artifacts rather than mandated on every file.