Early-Stage Documentation

We have years of visuals and vector work: Procreate sketches, Illustrator and Photoshop boards, InDesign decks, Sketch files, Figma files from several points in time. Finding and reusing any of it is always a struggle.

Mark has made attempts at archiving, and they're layered. The design.1.0 → 4.0 generations on Drive say where a file belongs. The _archive/design.*.history.N.ai boards gather old work onto artboards, and the repo's /archive was cut from four of those boards, so it shows the boards and not the originals.

The Drive holds 1,141 files and 14.2 GB, including 105 sketch PSDs (4.6 GB) from 2023. Most names carry no date, and nothing ties a file to the cycle or startup phase it came from.

The audience is us first. We need to understand and reach our own history before we use it to tell the story, first to each other, internally.

Separately, the cycle detail page renders CYCLE.md as written. c121's page is 7,300 px and ~2,270 words, its first image sits ~5,000 px down, and commit hashes run through the prose. It reads as a ledger, not a story.

1. Find: a committed catalog of the Design drive. For every file: where the original is (path + Drive link from its Drive ID), what it is (format, generation, discipline), when it was made (name date → creation date → mtime, marked by which), and a preview.
2. Place: each file tied to a cycle where one exists, otherwise to a startup phase (archive era) and design generation. Each tie is marked confirmed (Mark ruled), candidate (name/date match) or inferred (folder/date only).
3. Ingest: a written protocol and a skill for new and backlog work: export → place → tell. It covers Procreate on the iPad, Illustrator, Photoshop, InDesign, Sketch and Figma. The "tell" step comes first in spirit: what was the question, what did this try, what came next.
4. Tell: the first internal stories built from the library. Candidates: the 2023 sketches, the QPT.lab.dash-3.14 → 3.18 series, the brand history.md.
5. Cycle detail page: story first, record second. Lead image and beats up top. Key Changes, Decisions and Artifacts fold below, and hashes become chips. Detail page only; the /cycles index is out of scope.

Done = from the design site, anyone on the team can find a 2023 sketch or a 2025 deck, see it, open its original on Drive, and see which cycle or phase it belongs to. New work arrives through the skill. The c121 page reads as a story.

• Read-only source: ~/Library/CloudStorage/GoogleDrive-mark@qpoint.io/Shared drives/Qpoint Shared/Design. No renames or moves there without Mark's say-so.
• Repo:
  • a catalog script (scripts/) and its data (server/data/ or content/);
  • thumbnails under public/ (derivatives only);
  • archive taxonomy (server/data/archive-meta.ts, content.config.ts);
  • the /archive skill and/or a new ingestion skill (.claude/skills/);
  • /document-cycle (to add an ingestion step);
  • the cycle detail page (app/pages/cycles/[project]/[id]/index.vue) and its API (server/api/cycles/).
• Everything deploys to the design site behind Access, all of it.
• Out of scope:
  • the /cycles index;
  • Figma file-by-file specifics (we only note that several Figma files exist from different points in time);
  • external storytelling (video, talks, partners).

Phase 0 is done; the rest are proposed. Each phase is planned in detail when it starts.

• 0. Discovery (done 2026-10-23): discovery.md covers the formats on disk and the existing tooling, and audits the cycle pages. drive-survey.md covers the Drive's shape, the generations against startup phases, naming, Drive IDs and the first cycle candidates.
• 1. Catalog (built 2026-10-23): a read-only, metadata-only walker over the Drive. It records path, generation, discipline, format, size, dates and how each date was known, the Drive ID and link, and skips temp files. It writes a committed catalog and a /library (working name) page to browse by generation, phase, discipline and format.
• 2. Previews (built 2026-10-23): a background batch that makes thumbnails and web images (sips/qlmanage for PSD/AI/PDF, .sketch previews by unzip, InDesign by embedded preview). It caches, budgets for the deploy size, and works through the 4.6 GB of sketches in batches, since most files are online-only.
• 3. Associate: proposals of cycle, phase and generation with a confidence level, reviewed with Mark one folder at a time. This also fixes the taxonomy:
  • split type from fidelity (sketch · wireframe · mock · built) and medium (procreate · illustrator · photoshop · indesign · sketch-app · figma · paper);
  • make design-phase follow the Drive generation;
  • add source = Drive ID and path.
• 4. Ingestion protocol and skill: export → place → tell.
  • Per-medium export recipes, e.g. Procreate on the iPad → design.4.0/<discipline>/…/sketches/YYYY.MM.DD.<subject>.psd.
  • A short interview for the story.
  • Draft archive entries with the same subject key the captures use, so /cycles/evolution/<subject> can start at the sketch.
  • Wire it into /document-cycle.
• 5. Tell: the first two or three internal stories as beats (image + 1–3 sentences), for us.
• 6. Cycle detail page: moved to c124 Cycle Stories on 2026-10-26 (c124 D1). c122's beats become c124's outcome cards. The scope below is kept for reference.
  • story-first header (status, focus, lead image);
  • beats from a STORY.md or a ## Story section, falling back to the visual record;
  • the record collapsed beneath, with hashes as chips;
  • verified on c121, c107 (which has a STORY.md) and one recordless cycle.

• Discovery (2026-10-23): formats on disk, existing archive tooling, and a measured cycle-page audit (discovery.md). Mark's answers (answers-prompt.md): Procreate exports live in the shared Design drive; several Figma files from different times; audience is us first; detail page only; everything deploys behind Access. A first Drive survey (drive-survey.md): 1,141 files, 14.2 GB, generations 1.0–4.0, 105 sketch PSDs, permanent Drive IDs, nine cycle candidates.
• Catalog (2026-10-23), Phase 1 (catalog-prompt.md):
  • scripts/drive-catalog.mjs (npm run drive-catalog, ~3 s) walks the drive read-only. It lists folders, stats files, reads each item's Drive ID from the com.google.drivefs.item-id#S xattr, and reads the online-only (SF_DATALESS) flag in one stat pass. It never opens a file.
  • It writes server/data/drive-catalog.json: 1,137 files, 248 folders (every folder has a Drive ID), 14.1 GB, 78 temp/dot files skipped.
  • Each file records path, Drive ID, title, format, kind, generation, discipline, size, whether it's on this Mac, and a date with precision and source. The date sources: 203 from the file name, 277 from a folder name, 657 from the file's own times.
  • 52 files (0.7 GB) are on this Mac; the rest are online-only. 56 files have no Drive ID yet, all of them local, so Drive for desktop may not have uploaded them.
  • GET /api/library adds a startup phase inferred from the date against the archive's eras: 946 ideation, 87 pre-seed, 101 seed, 3 before Qpoint.
  • /library (off the main menu for now):
    • generation cards with file count, size and year span;
    • search, plus kind and phase filters;
    • the layer's UxFileTree over the drive's own folders;
    • a detail panel: the date and where it came from, the phase, size, on-Mac state, and links to the original and its folder on Drive.
    • The selected file lives in ?f=<drive path>, so a link points at one file; the tree scrolls to it on arrival.
  • Verified headless (Playwright, system Chrome, 1440 × 900): deep link in view; Design 1.0 + Raster + "early-deck" → 42 files; click → URL and panel update; no page errors.
  • Incident (Phase 1): while removing a debug line, an edit joined two lines in the page's script. The syntax error took down SSR for every route on :3000 ("IPC connection closed"). Mark's terminal-started dev server was stopped and restarted under the design launch config. Found by moving the new files aside and adding them back one at a time; fixed in the page.
• Previews (2026-10-23), Phase 2 (previews-prompt.md):
  • scripts/drive-previews.mjs (npm run drive-previews) writes one 640 px WebP per file to public/library/thumbs/<drive id>.webp (14 MB for all of them), plus server/data/drive-previews.json. Options: --only <prefix>, --list <file>, --retry, --force.
  • Downloads: QuickLook can't make Drive download an online-only file; it waits forever. So each online-only file is copied to a temp folder (the copy makes Drive download it), previewed from the copy, and the copy deleted. With a non-blocking copy and 4 workers, the whole drive (~14 GB) took under 10 minutes. Adobe's InDesign QuickLook extension hangs even on local files, so every tool runs under a timeout.
  • Methods tried in order, per format:
    • sharp for images and SVG;
    • sips → QuickLook → the XMP thumbnail for PSD;
    • QuickLook → XMP for PDF/AI;
    • XMP for InDesign/EPS;
    • previews/preview.png for .sketch.
    
    A blank result moves on to the next method. White-on-transparent art is retried on ink.
  • Results: 1,111 previews (354 sharp, 128 SVG, 334 QuickLook including the 25 blanks, 234 sips, 52 XMP, 9 Sketch); 6 rendered on ink.
    • 25 stay blank: PSD/AI files saved without a flattened image or a thumbnail, which only Photoshop/Illustrator can draw. The page says so and names the save option that would fix it.
    • 2 .indb InDesign books have no image of their own.
    • One pair of files shares a Drive ID (QPT.2025.Q3/Q4.overview.ai), so shared IDs take a path-hash suffix.
  • /library: the API merges the previews. Generation cards count previews. The detail panel shows the preview, or the reason there's none. A Folders ⇄ Grid switch (?view=grid) shows the filtered files as pictures, 240 at a time. The 2023 sketches: 110 of 111 under sketches/ have previews.
  • Verified headless at 1440 × 900: grid, selection, deep link, the blank-file note, no page errors. A random 40-preview sheet read cleanly.
  • For Phase 3: the same artwork often appears as @2x/@3x PNG + SVG + .ai, so grouping variants by stem will shorten the library a lot.
• Illustrator artboards (2026-10-23) (artboards-prompt.md → artboards-plan.md):
  • The probe covered 15 files and 173 artboards. A PDF-compatible .ai is one PDF page per artboard, matching in order and size. Its Illustrator private data (zstd/zlib native PostScript) holds each artboard's name, canvas position and UUID. Page order isn't canvas order.
  • Plan revised on Mark's note: sequences and subjects are tagged and stitched by hand, in post; extraction stays automatic and records facts only.
  • Steps 1–2 built. scripts/drive-artboards.mjs (npm run drive-artboards) has the same read-only, temp-copy, timeout and cache contract as the previews. It uses pdfinfo + mutool + zstd (streamed through tr/grep) + pdftoppm + sharp.
    • Rendering: 1,200 px long edge (400 px short edge beyond 3:1) plus a 320 px thumb, as WebP.
    • Results: all 255 .ai files, 3,627 artboards, 120 MB, no failures. 246 files have canvas positions; 396 artboards have custom names, mostly on the history boards, where they name the source file.
    • 9 files kept only their first artboard in the PDF copy (3–38 artboards each, ~140 in all, e.g. QPT.dash-1.0.ai 1 of 24, QPT.lab.dash-3.15.topnav-filter.ai 1 of 38). They show "1 of N readable" and wait for the Illustrator pass (plan step 5).
    • Two fixes on the way: one file's private data decompresses to 1.4 GB, more than a Node buffer can hold, so the records are now filtered in a shell pipeline. A zstd early exit no longer crashes the run.
  • /library:
    • "Inside " draws an .ai file's artboards at their real canvas positions and sizes. Clicking one opens UxLightbox at 1,200 px; arrows step in reading order, and ?a=<n> links one artboard.
    • The detail panel gets an Artboards row, and the generation cards count artboards (Design 1.0: 1,268).
    • The /api/library payload is now 1.2 MB.
  • Quick filters (Mark, same day):
    • Illustrator (.ai): 255 files.
    • Presentations: 381 files, matching any folder named for a presentation, deck, pitch or slides, or "deck" in the file name. Deck folders also hold their image assets.
    • The two combine with AND: 45 .ai presentation files.
  • Deployed (2026-10-23) as 3e5d09dc10 = design 7b2668823f + 43 uncommitted from other threads, layer 0.9.35. 17,175 files, 777 MB; Cloudflare Pages caps a deployment at 20,000 files, so the next large image set needs a plan (R2, or fewer derivatives).
    • /library had no inbound link, so the static crawl from / would have skipped it. 7b2668823f links it from the /archive intro and adds it to nitro.prerender.routes.
    • Verified on design-f39 (headless, system Chrome): /library, its data, previews and artboard images all return 200. The QPT.index-v20.ai deep link renders 7 artboards in ~0.35 s, a click opens the lightbox with ?a=3, and the quick filters give 45 .ai presentation files. No page errors.
    • The build's error lines are older ones (todos cycle-ID 404s, /components/data/data-timeline 500).
  • Verified headless at 1440 × 900: QPT.index-v20.ai (one row, canvas order 2, 1, 3…), the 46-artboard dashboard history board (clusters with their title artboards), the lightbox, arrow keys and Escape with the URL following, and a partial file's note. No page errors.
• Sketches and a larger preview (2026-10-24 → 27, Mark):
  • Sketches quick filter (694e1345eb): PSDs in any folder named for sketches, 120 files, 5.1 GB. It leaves out .sketch (Sketch app) files, the dynamic-sandbox PNG copies, and the 24 Procreate illustrations in design.3.0/illustration/originials/.
  • ↑/↓ preview (1ce48f3487): in the folder tree, the selection follows focus, so arrowing opens each file and updates ?f=. Tabbing in doesn't select. Built on the page (a focusin handler), not in UxFileTree; a selectionFollowsFocus prop is the layer candidate if another page wants it.
  • Preview sizes (5e12ec76a5): S / M / L / XL (360 / 480 / 680 / 900 px) and a drag handle between tree and preview (←/→, double-click for M), remembered per browser; the tree keeps 360 px.
  • Large sketch previews (6d44fa9c64): drive-previews --large writes 1,600 px WebPs to public/library/large/. The 117 sketches with a picture have one (5.3 MB; the 3 blank PSDs are skipped). /library offers both in srcset, so the large one loads at XL on a normal screen and at any size on retina.
  • Deployed (2026-10-27) as ba4ff7ce7a = design 6d44fa9c64 + 40 uncommitted from other threads. 17,877 files, 815 MB (Cloudflare's cap is 20,000). Verified on design-f39: arrows step 2023-sf-roundtable → early-deck-2.1 → early-deck-2.2 with the panel following, XL is 900 px and loads the large WebP (200), the handle shows, no page errors. The build's error lines are older ones (cycle-doc 404s, /cycles/weeks/1999-12-27).

—

• Drive hygiene (renaming Untitled_Artwork N, fixing originials) is Mark's call. Default: leave names alone and carry a clean title in the catalog.
• .gdoc text (the Product Design/ specs) needs the Drive/Docs API. Default: catalog them as pointers.
• Dates in design.1.0/sketches/ cluster on 2023-09-01, which looks like a batch copy. Real drawing dates may need Procreate's own export metadata or Mark's memory.