# design guide

this document describes the design system for notmyresume.dev.

## design philosophy

| principle | description |
|-----------|-------------|
| **dark mode** | deep blacks (#0a0a0a) with careful contrast for readability |
| **no paragraphs** | diagrams, tables, and bullets only. dense visual layout. |
| **skimmable** | each section takes less than 5 minutes to read. structured for scanning. |
| **playful but rigorous** | direct voice without false modesty. serious work, light touch. |

## color palette

| name | hex | use case |
|------|-----|----------|
| background | #0a0a0a | page background |
| surface | #141414 | cards, containers |
| border | #2a2a2a | dividers, outlines |
| text | #e8e8e8 | primary copy |
| dim | #888 | secondary text, labels |
| muted | #555 | tertiary text |
| accent (orange) | #f97316 | cta, highlights |
| ocean (blue) | #0ea5e9 | data, technical |
| cloud (purple) | #a78bfa | process, conceptual |
| green | #22c55e | success, positive |
| red | #ef4444 | warning, stopped |
| yellow | #eab308 | caution, paused |
| blue | #3b82f6 | neutral info |

## typography

| role | font | use |
|------|------|-----|
| body text | Inter | all prose content |
| code/labels/technical | JetBrains Mono | skill tags, code blocks, metric labels, technical identifiers |

## component patterns

**TLDR table**
- two column: label/value
- appears at top of every section
- gives you the kernel of the idea in 30 seconds

**metric cards**
- large number with small label below
- used for quantitative findings
- orange accent or appropriate color coding

**flow diagrams**
- left to right or top to bottom
- boxes with labels, arrows between
- show process or causal flow

**timelines**
- vertical or horizontal
- milestones with dates
- can include status pills at each step

**status pills**
- green: active, complete, go
- yellow: paused, in progress, caution
- red: stopped, blocked, failed
- blue: neutral, info, pending

**bullet lists**
- use arrow prefix: "-> " before each item
- no traditional bullets
- keep lines short and scannable

**callout blocks**
- border-left style with accent color
- used for key insights or warnings
- quote or concept styling

**verdict bars**
- horizontal status display
- shows project state at top level
- green/yellow/red only

**architecture diagrams**
- boxes for components
- lines for connections/data flow
- labels on flows explain purpose

## content rules

| rule | why | example |
|------|-----|---------|
| NO paragraphs | paragraphs hide information density | bad: "The system was built in three phases..." good: bullet list or flow diagram |
| NO emdashes | use "not" or commas instead | bad: "this was hard -- really hard" good: "this was hard, really hard" |
| lowercase headers | consistent voice, less formal | good: "the problem" not "The Problem" |
| TLDR table first | readers want answers before details | every section opens with tldr |
| status pills for status | visual parsing is faster | "status: <span style='yellow'>paused</span>" not "currently paused in Q2" |
| tables for comparisons | side by side beats narrative | use table instead of "A is better than B because..." |
| bullets for lists | scannability over prose | use bullets with arrow prefix |
| flow diagrams for processes | visual flow beats steps | show how data moves, not "first you do X" |

## case study structure

each case study follows this pattern:

1. **back link** to case studies index
2. **title** (lowercase)
3. **subtitle** (one sentence, establishes the question)
4. **TLDR table** with: kernel, hypothesis, verdict, skills
5. **content blocks** each with:
   - label line (section header, lowercase)
   - appropriate visual (table, diagram, bullets, metric)
   - no paragraphs between blocks
6. **honest self-assessment** table
7. **verdict bar** showing project state
8. **research artifacts** table (links to external work)
9. **skills** section with monospace, border-only tags

## voice guidelines

| principle | example |
|-----------|---------|
| lowercase | "the problem" not "The Problem" |
| direct | "this didn't work" not "we faced challenges" |
| self-aware | "i explored this" not "i failed at this" |
| not self-deprecating | "this was wrong" not "i was stupid" |
| honest uncertainty | "still unclear why" not "obviously because" |

## AI disclosure

-> always present when AI was used in research or execution
-> honest about what it was used for (architecture, code, exploration)
-> not apologetic, just factual
-> example: "built almost entirely using AI tools (claude code, openai codex)"

## skill tags

-> monospace font (JetBrains Mono)
-> border-only style, no fill
-> used to label learned techniques
-> example: `shipfinance` `stablecoin-design` `market-sizing`

## adding new case studies

the process mirrors how this guide itself was created (during a Cowork session with Claude):

1. start with the conversation as research artifact
2. extract the TLDR table structure (kernel/hypothesis/verdict/skills)
3. organize content into blocks with appropriate visuals (not paragraphs)
4. build honest self-assessment table
5. add verdict bar (green/yellow/red)
6. include research artifacts table with real links
7. review: no paragraphs, no emdashes, lowercase, all sections have visual structure

the conversation itself serves as the design process. all thinking happens in the open.

## automation and maintenance: the weekly self-update agent

the site is now maintained by a scheduled Cowork agent that runs every sunday at 6pm local time (cron `0 18 * * 0`). the agent uses the claude agent sdk on claude opus 4.6.

### what it does

- reads the 55-file karpathy-style research wiki's index.md and log.md
- identifies every page whose changelog was touched in the last seven days
- reads the current site source files: index.html, hop.md, cloud-brain.md, maritime.md, about.md, portfolio-full.md
- diffs wiki content against site content
- runs every candidate edit through a privacy filter
- writes exactly one markdown file per run at `proposed-updates/YYYY-MM-DD.md`

### what it cannot do

- no git commits
- no vercel deploys
- no direct edits to index.html or any .md source file
- no browser control, no web scraping
- no reading the wiki's raw/ folder (unfiltered interview notes, hard-prohibited)

### proposal file structure

every proposal file has exactly four sections:

1. **what's new in the wiki**. every wiki page whose changelog was touched in the last seven days, summarized
2. **proposed edits**. concrete bullet or table changes that passed the privacy allowlist
3. **flagged for manual review**. edits the agent is not sure about, with the uncertainty noted
4. **audit trail**. anything deliberately stripped, with the denylist rule that fired

## pii methodology: deny-by-default allowlist

the governing heuristic: would ayush be comfortable if the source of the insight read it on the public site? if yes, allow. if unsure, flag. uncertainty always routes to manual review.

### allow rules (a fact is eligible only if it matches one)

1. **already public.** the same fact is already on the site and just needs a refresh
2. **public source.** the wiki page cites a published article, press release, SEC filing, or named dataset
3. **historical / frozen.** content about HOP network (shipped), curinos (former employer, frozen data), or public biographical context
4. **public research pattern.** technical design, methodology, or frameworks that describe how ayush thinks rather than who he is talking to (pull-lift evaluation, MCP tooling, karpathy wiki schema itself)

### deny rules (always stripped or flagged)

- megaeth internal strategy: token plans, treasury, roadmap, unannounced partnerships
- active deal or partner names
- non-public pricing and unit economics pulled from private conversations
- internal treasury figures
- curinos client or bank identifications
- personal contact info (emails, numbers, anything doxxable)

### primary research: the trickiest category

interview content is split into two buckets:

- **allowed:** business-neutral, non-confidential insights where the insight itself is not commercially sensitive, no specific person or company or active deal is identifiable, and the source was not marked confidential. framed as generic "industry research revealed X" without attribution. example: "most crew payments are already denominated in USD at scale" is a pattern learned from conversations but does not point back to any specific counterparty.
- **flagged or stripped:** quoted sentiments tied to identifiable roles, reverse-identifiable anonymous attributions, specific pricing or deal figures from private conversations, active-counterparty quotes, anything competitively sensitive. example of flagged framing: "a CFO of a mid-size ship manager told me they already settle in USD" is identifiable and reverse-linkable.

### case-study-specific guardrails

on top of the global filter, each case study has its own default mode:

- **HOP network:** allow-by-default. frozen and shipped
- **cloud brain:** allow-by-default for technical and design content. flags specific megaeth integration numbers and contributor names
- **maritime:** allow-by-default for public competitive data (marcura, kinexys, tradelens, mastercard/bvnk). strips any quote tied to an interviewed executive or any insider-access ship management detail

## autonomy tier and maintenance loop

### why autonomy is deliberately low

- the agent writes exactly one markdown file. no git, no vercel, no source edits
- this is the "propose, don't merge" pattern: agent does the tedious diffing and privacy-filtering, ayush does the 10-minute review and the publish
- if the agent gets a judgment call wrong, blast radius is zero: the bullet just does not get accepted from the proposal
- the next tier up would be auto-committing section 2 edits to a branch and opening a PR. deferred until a few weeks of proposal quality has been observed

### the maintenance loop

- **consistent rejections → tighten the allowlist.** a rule that lets too much through is too loose
- **consistent manual additions → loosen the denylist.** if ayush keeps adding facts the agent did not surface, the filter is overclassifying
- **the task prompt is editable in-place** in the cowork scheduled-tasks system. already revised once to loosen the primary-research rule when the first version over-stripped business-neutral insights
- **the revision rule:** never relax a privacy guardrail without being able to articulate why the original concern was wrong