# Design brief: reading interface for a personal research wiki

You are designing the web reading interface for a personal research wiki from
scratch. No interface exists yet. Design what this corpus and these reading
tasks actually need. Do not assume any conventional documentation-site layout
is correct; derive the design from the material below.

## 1. What the thing is

A single person's research vault: 554 interlinked Markdown notes, maintained
over time by the owner and by AI agents. It is not documentation, not a blog,
not a public knowledge base. It is a working analytical instrument: the owner
researches contested questions (privacy law, surveillance, criminal procedure,
adolescent online safety, security engineering, Swedish and EU law) and the
wiki holds the accumulated evidence, definitions, and warranted conclusions.

Two ways it is read:

- **Deep reading.** Open one note and read 2,000--5,000 words of dense
  analytical prose end to end.
- **Traversal.** Follow an argument across notes: a conclusion to its premises,
  a premise to the evidence behind it, a claim to the archived PDF it rests on.

Prose is the product. Everything else is apparatus around it.

## 2. Content model

Every note is a Markdown file. The filename is its identity; wikilinks target
the filename. Frontmatter fields, all always present:

| Field | Meaning |
|---|---|
| `title` | Display title. Usually equals the filename; diverges for source notes naming external works |
| `subtitle` | Optional second half of a title (26 of 554 notes have one) |
| `type` | One of nine kinds; see below |
| `aliases` | Alternate names for search and autocomplete |
| `tags` | Topic vocabulary; 288 distinct tags across the vault |
| `sources` | Note-level provenance inventory: local file paths and external URLs. Ranges from 0 to 66 entries |
| `status` | Lifecycle: `seed`, `working`, `stable`, `stale` |
| `updated` | Date last materially edited |
| `review_after` | Optional date when time-sensitive claims need revalidation (246 of 554 notes carry one) |
| `abbr` | Optional local abbreviation definitions, rendered as tooltips on first use (433 notes carry these) |

### The nine note types, and why the distinction matters

Type is the vault's central ontology. It is not decoration; it tells the reader
what warranty the note carries. A reader must be able to tell at a glance
whether they are looking at evidence, a definition, or a conclusion.

| Type | Count | What it is |
|---|---|---|
| `source` | 192 | A card describing one archived artifact (PDF, saved web page, transcript) held immutably on disk. Evidence |
| `entity` | 148 | A named individuated thing: a person, company, product, protocol, statute, court judgment |
| `concept` | 90 | A reusable idea, mechanism, doctrine, or category. Defines what something *is*. Other notes argue *from* it |
| `synthesis` | 68 | A warranted conclusion argued from cited evidence. Asserts a proposition the vault has a stake in |
| `question` | 21 | An open research question the vault wants answered. States what is known and what evidence would settle it. This is the research frontier |
| `event` | 18 | Something that happened: a breach, a criminal case, a regulatory action, a controversy |
| `meta` | 12 | Pages about the wiki itself |
| `index` | 5 | Curated entry points routing readers into a region |
| `essay` | 0 | The owner's own position, not warranted by sources. Allowed, currently unused |

The load-bearing distinction for a reader: `source` (evidence someone else
produced) vs `concept`/`entity` (building blocks) vs `synthesis` (a claim this
vault is making) vs `question` (an admitted gap). Colour alone must not carry
this; it must survive greyscale and colour blindness.

### Status, and why it is not just a badge

| Status | Count | Meaning to a reader |
|---|---|---|
| `stable` | 432 | Checked at its stated scope; safe to rely on |
| `working` | 119 | Usable, but has a *known material gap* or unresolved contradiction |
| `seed` | 3 | A capture or skeleton; not yet standing on its own |
| `stale` | 0 currently | Time-sensitive claims now known unsafe to rely on until revalidated |

`review_after` is a separate freshness schedule. A note can be `stable` and
overdue for review at the same time, and a reader deciding whether to cite it
needs to see both.

## 3. Corpus shape (design for these numbers, not for a demo)

- 554 notes in one flat namespace, no folders, no hierarchy.
- Length ranges from ~90 words (a short source card) to ~5,600 words for the
  longest subject note; one maintenance log runs to 47,000 words.
- 2,303 resolved links among 537 subject notes. The most-connected note has 36
  inbound and 49 outbound links. Some notes have zero of either.
- 288 tags. The largest covers 240 notes; a long tail is used once or twice.
- Unresolved wikilinks ("redlinks") are deliberate and permanent: they mark
  subjects the vault wants to write about. They are a research queue, not
  broken links, and must read as *wanted*, not as *error*.
- Some notes are orphans (nothing links to them) or dead ends (nothing links
  out). The interface should not pretend the graph is tidy.

## 4. Everything that must render inside a note body

The body is Markdown starting at heading level 2. It uses:

- Headings, H2 through H4, forming an outline of a long argument.
- Long analytical paragraphs. This is the dominant element.
- **Wikilinks** to other notes, inline in prose. Two states: resolved, and
  unresolved (a wanted page). Both appear mid-sentence and must not shred the
  line. 83 notes average several links per paragraph.
- External links, and links to archived evidence files on disk (PDF, HTML).
- **Footnotes** (124 notes). These carry claim-level citations, distinct from
  the note-level `sources` inventory. The distinction is meaningful: `sources`
  says what informed the note, a footnote says what supports *this sentence*.
- **Callouts** (118 notes), in 13 semantic families: note, abstract, info,
  todo, tip, success, question, warning, failure, danger, bug, example, quote.
  Each may carry a custom title. Used for a hard legal boundary, a technical
  invariant, a scope caveat, a decision rule.
- **Tables** (83 notes). Often comparisons across repeated dimensions; some are
  wide and need to survive a narrow viewport.
- **Task lists** (43 notes), checked and unchecked, used for real open work.
- **Mermaid diagrams** (29 notes), flowcharts and graphs, rendered client-side.
  Some are large enough to need zoom, pan, and fullscreen.
- **Vega-Lite charts** (3 notes) with inline data.
- **Block quotes** with attribution.
- **Maths** (14 notes), inline and display, rendered as MathML.
- Code blocks and inline code.
- Abbreviations with tooltip expansions on first use.

## 5. What the reader needs from the apparatus

Design decisions here are yours. This is the list of jobs, not a feature spec.

1. **Judge a note before trusting it.** Type, status, freshness, how much
   evidence stands behind it, whether a review is overdue.
2. **Navigate a 5,000-word argument.** Know where they are in it and jump.
3. **Find one note among 554.** By title, alias, tag, heading, or prose. The
   full text of every note is available client-side for search.
4. **See what a note is built on.** The `sources` inventory, and separately,
   claim-level footnotes; some sources are archived files sitting on disk.
5. **See what builds on this note.** Backlinks are computed at build time.
6. **Move laterally.** Outgoing links, backlinks, shared tags, notes in the
   same link neighbourhood.
7. **See the frontier.** Which questions are open, which redlinks are wanted,
   which notes are overdue for review. The vault treats not-knowing as
   first-class content.
8. **Copy a reference to a note** for pasting into another note as a wikilink.
9. **Read on a phone.**

There are also tag pages (one per tag, listing its notes and related tags) and
graph pages (a whole-vault link graph, a tag graph, per-note local graphs).

## 6. Hard technical constraints

These are not negotiable; a design that violates them cannot ship.

- **Static HTML.** One pre-rendered page per note, plus one shared stylesheet
  and one shared script. No build step beyond a Python generator. No
  framework, no bundler, no React, no Tailwind, no CDN, no external network
  request of any kind at view time.
- Must work opened directly from `file://` as well as over HTTP.
- **Vanilla JS only**, and not much of it. It may read one preloaded data blob
  containing every note's title, type, tags, headings, links, and full text.
- **Light and dark themes**, both first-class, following the system preference
  with a manual override.
- **Accessible**: WCAG AA contrast, meaning never carried by colour alone,
  full keyboard operation, correct landmarks and labels, visible focus.
- Fonts are bundled locally. Assume available: `Source Serif 4` (serif),
  `Source Sans 3` (humanist sans), `Source Code Pro` (mono), and a maths serif.
  Use system fallbacks in the mockup so it renders anywhere.
- 554 pages get generated in one pass, so the design must be expressible as one
  stylesheet with no per-page variation beyond data attributes.

## 7. Real content to use in the mockup

Use this actual note. Do not invent lorem ipsum, and do not shorten it into
bullet points; the design must be tested against real prose density.

Frontmatter of the sample note:

```yaml
title: Case for privacy and security
type: synthesis
aliases: [why privacy matters, case for privacy]
tags: [privacy, security]
sources: 66 entries, mixed local PDFs and external URLs
status: stable
review_after: 2027-01-13
updated: 2026-07-19
```

Body opening (verbatim; wikilinks shown in double brackets):

> Privacy is not a claim that a person has something shameful to hide. It is
> the ability to decide who can learn intimate facts about one's life,
> relationships, movements, finances, health, politics, and vulnerabilities.
>
> Security is the practical ability to keep those facts, accounts, devices, and
> services confidential, available, and accurate. Privacy without security
> leaks. Security without privacy can become a tightly controlled surveillance
> system.
>
> The two are connected but not interchangeable. [[Privacy threat modeling]]
> should always ask both: who could obtain or alter this information, and who
> should not have been collecting it in the first place?
>
> The core claim of this synthesis is that privacy limits the conversion of
> information into [[Data as coercive power]]. Across commercial breaches,
> spyware campaigns, government databases, health systems, dating platforms,
> and forensic extraction, the recurring pattern is the same: concentrated
> sensitive data becomes leverage when weak controls, covert access, or
> exploitative sharing expose it.
>
> ## Why privacy is a right rather than a preference
>
> Privacy protects autonomy, dignity, intimacy, association, bodily integrity,
> confidentiality, and the conditions for a self-authored life. People need
> confidential space to form relationships, deliberate, experiment, change
> their minds, seek care, and manage the boundaries between family, work,
> politics, and intimacy.

Real section headings from this note, for an outline: "Why privacy is a right
rather than a preference", "Why privacy is a safety issue", "Privacy supports
equal participation", "Privacy is market infrastructure", "A map from data to
harm", "Case studies" (with sub-headings: Ashley Madison, Equifax, Vastaamo,
SpyFone, Grindr, Pegasus against El Faro, Afghan relocation data leak, OPM,
VTech, 23andMe), "Why lawful extraction is still an ethical question",
"Objections", "Regulatory setting".

Real note titles from the vault, for any navigation or list surface:

```text
Scandinavian legal realism          synthesis   stable
Rättssäkerhet in Swedish criminal cases  synthesis  stable
Alf Ross                            entity      stable
Anonyma vittnen                     concept     stable
23andMe data breach                 event       stable
ASA statement on p-values           source      stable
Apple Private Cloud Compute         entity      stable
Are Swedish mobile-extraction filters disclosed at trial?  question  working
Age assurance                       concept     working
Android app distribution trust models  synthesis  stable
Cellebrite                          entity      stable
Data as coercive power              concept     stable
False accusations as an epistemic risk  concept  stable
GC and Others C-136/17              source      stable
Kevinfallet                         event       stable
Memory Integrity Enforcement        entity      stable
Reproducible builds                 concept     stable
UK Online Safety Act                entity      working
```

Real tags, with note counts: privacy (240), Sweden (153), security (79), law
(65), United-States (63), children (59), criminal-justice (52), AI (51),
business (42), open-source (36), EU (32), VPN (27), digital-forensics (25),
surveillance (25), Android (24), online-safety (24).

A real source note, entire, to show how short some notes are:

> **ASA statement on p-values** — type source, tags: statistics,
> scientific-method, evidence. Sources: a local PDF and a DOI.
>
> The ASA issued this statement in 2016 to address widespread misuse of
> statistical significance and p-values. The local PDF is the association's
> official release. The statement defines a p-value in relation to a specified
> statistical model. It says a p-value does not measure the probability that
> the studied hypothesis is true, the probability that chance alone produced
> the data, the size or importance of an effect, or the strength of evidence by
> itself. The statement supports the comparison in [[Probabilistic
> interpretations of beyond reasonable doubt]].

## 8. What to deliver

One **self-contained HTML file**: all CSS and JS inline, no external requests,
opens correctly from `file://`. It must be a real working page, not a picture
of one — actual HTML and CSS that could be lifted into the generator.

It must show, in one page:

1. A full note-reading view using the real sample content above, long enough
   to judge prose rhythm and typographic colour at real density.
2. The metadata apparatus for that note (type, status, freshness, provenance).
3. The navigation and search affordance, in whatever form your design argues
   for.
4. An outline or wayfinding affordance for the 5,000-word argument.
5. Connections: backlinks, outgoing links, tags.
6. At least: one callout, one table, one blockquote with citation, a footnote
   with its reference, a task list, an inline resolved wikilink, an inline
   unresolved redlink, and a code span.
7. A working light/dark toggle.

Also include, below the main view or reachable in-page, compact treatments of:

- a search result list,
- a tag page,
- the short source note,
- a `question` note showing an open frontier item,
- a `working` note showing its known gap.

At the very top of the file, in a plainly styled block that is clearly outside
the design (mark it `<div class="brief-note">`), write 200--400 words stating:
what you decided the design must do, the two or three central decisions you
made, what you deliberately rejected, and where you are uncertain. Be
concrete about tradeoffs; do not write marketing copy about the design.

## 9. Standards

- Every decision must be justified by something in this brief, not by
  convention. If you reach for a familiar pattern, it must earn its place
  against this corpus.
- Prose legibility outranks every other consideration. If an apparatus
  competes with the reading, the apparatus is wrong.
- No gradients as decoration, no glassmorphism, no drop shadows used for
  hierarchy alone, no stock imagery, no icons that duplicate a visible label
  without adding meaning, no animation that is not functional.
- Density is a real question with 554 notes and 288 tags: do not design a
  landing page that would break at scale, and do not design a dense dashboard
  that ruins the reading.