HD inkling Vision document

Personal knowledge artifact

inkling — Vision.

A personal document kit for ideas, vision docs, HLDs, LLDs, and learning notes: agent-generated, single-file, warm, readable, interactive HTML.

Markdown is excellent. What it can't carry is the ceiling.

Markdown is excellent as a low-friction writing surface. Agents produce it quickly. Humans can diff it, copy it, and publish it almost anywhere. But for high-value thinking documents, Markdown often makes the output feel unfinished.

The missing quality is desire. A vision doc should feel like something worth returning to. An architecture doc should make the system easier to hold in your head. A learning note should feel like a field guide, not a dumped transcript.

The goal is not prettier notes. The goal is notes that pull you back into the thinking.
Markdown keeps

Speed, portability, version control, agent friendliness, and plain text clarity.

HTML adds

Layout, interaction, diagrams, navigation, print polish, and visual hierarchy.

The bet

The agent can absorb the complexity, while the human keeps the writing flow.

What this kit must believe.

Principle 01

Writing stays easy.

The user should not hand-author elaborate HTML. The agent should transform natural-language intent into a polished document.

Principle 02

Beauty serves return visits.

The visual system should make the document feel calm, serious, and inviting, like a notebook you want to reopen.

Principle 03

Interaction must explain.

Interactivity is only worth adding when it clarifies structure: diagrams, decision trees, timelines, comparisons, and drills into detail.

Principle 04

One file should be enough.

The default artifact should open in a browser, survive archiving, be easy to share, and require no app or server.

Start with four document types, not a platform.

The first version should be a disciplined set of document templates for the docs already being written. Keep the scope personal, useful, and shippable.

Vision

Why something should exist, what it believes, what success looks like, what is out of scope. Sections: Thesis · Why now · User & problem · Principles · Non-goals · Risks · Roadmap.

Start here
HLD

The high-level system design. Sections: System overview · Architecture diagram · Major components · Data flow · Boundaries · Tradeoffs · Risks.

Architecture
LLD

The implementation-level design. Sections: APIs · Schemas · Classes & modules · State transitions · Edge cases · Error handling · Test plan.

Execution
Learning

Material easier to revisit and internalize. Sections: Concept map · Key ideas · Examples · Mental models · Misconceptions · Exercises · References.

Study

The agent becomes the layout engine.

Click each stage. The human thinks in language; the agent turns that thinking into a durable artifact.

Interactive diagram

Capture raw thinking

Start with messy intent: a voice note, a pasted chat, a rough bullet list, or a half-formed idea. The source can stay informal.

The kit should carry thinking patterns, not just CSS.

A good doc kit gives agents reliable building blocks for common thinking moves. These are the patterns the first version should carry.

  • Framing notes — small cards that set context before the prose.
  • Decision records — what was chosen, what was rejected, and why.
  • Alternatives — explicit side-by-side options with tradeoffs.
  • Tradeoff tables — comparable rows on shared dimensions.
  • Risk registers — what could break, ranked.
  • Architecture diagrams — clickable nodes that explain themselves.
  • Timelines — sequenced steps with detail on demand.
  • Glossaries — light up terms inline as you read.
  • Next-action blocks — the call-to-do at the end of a doc.
  • Print-friendly summaries — a compact one-pager hidden in the same artifact.
Not Markdown with nicer CSS

The document is designed as HTML from the beginning. Navigation, hierarchy, interactive diagrams, print styles, and reusable components are first-class. It is a better artifact format for serious personal docs, not a prettier export target.

The decisions taken so far.

Default to single-file HTML

Default to single-file HTML artifacts first. Do not build a notes app until the personal documents are clearly valuable.

Keep raw authoring optional

The user should not need to write HTML directly. Raw HTML is an output format, not the thinking interface.

Make structural edits agent-led

Text blocks can be editable in the browser for lightweight tweaks. Structural edits should still be handled by the agent so the file stays coherent.

What this is explicitly not.

Not in scope
  • Do not replace Notion, Obsidian, or a CMS in v1.
  • Do not build a full app before proving the personal artifact workflow.
  • Do not add interaction for decoration.
  • Do not make every note feel like a mini website.
  • Do not require a build step for the default output.

A practical path from one file to a system.

V0: Personal artifact

  • Create the four HTML templates.
  • Use them for real docs for two weeks.
  • Keep only components that get reused.

V1: Doc kit

  • Add a shared design system.
  • Create prompts for each document type.
  • Add reusable interactive diagrams.
  • Establish a small component vocabulary.

V2: Product surface

  • Package examples into a gallery.
  • Let others generate docs from prompts.
  • Explore whether people want this beyond personal use.

This is working if…

  • The generated HTML docs are more pleasant to revisit than Markdown.
  • The authoring workflow stays as fast as asking an agent for a Markdown doc.
  • The same visual language works across vision, HLD, LLD, and learning notes.
  • Interactive elements make hard ideas easier to understand.
  • The documents feel archive-worthy.

What we still don't know.

Should Markdown remain the source of truth?

With HTML as the rendered artifact, Markdown stays diff-friendly and agent-friendly. The render is the artifact; the markdown is the seed.

Should HTML files include editable regions, or should edits go through the agent?

Lightweight text edits in the browser are useful. Structural edits should still be agent-led so the file stays coherent.

How much JavaScript is acceptable in a single-file knowledge artifact?

Enough to enable interaction that explains structure; not enough to require a bundler. The runtime should fit in a few kilobytes.

Should the design system feel like a book, a notebook, a magazine, or a field guide?

Start with one warm-notebook theme and earn more themes by writing docs that visibly want them.

What is the minimum component set that covers 80% of serious docs?

Find out by writing real docs and watching what the agent reaches for twice. V1 extracts the recurring ones into a shared kit.