README.md

scarnecchia.net #

Personal site for Scarnecchia: writing, projects, design, photography, and CV.

Built with Astro 5 as a fully static site. There is no CMS and no database: all content lives as AT Protocol records on a PDS, fetched at build time via public XRPC endpoints and validated with Zod schemas. Publishing content means writing records to the PDS; the site picks them up on the next build.

drafts/*.md ──publish:post──▶ PDS records ──npm run build──▶ dist/ (static HTML)
Grain app ───────────────────▶   (curation record selects what appears)
Content Record type Route How it gets there
Essays / notes site.standard.document (path /writing/*) /writing/<slug> npm run publish:post
Project case studies site.standard.document (path /projects/*) /projects/<slug> npm run publish:post with section: projects
Photography social.grain.gallery + photos /photography, /photography/<rkey> Galleries made in the Grain app, selected via npm run publish:curation photo add
Design portfolio systems.numina.site.curation entries /design npm run publish:curation design add
CV id.sifa.profile.* records /work Edited directly on the PDS

Note the naming: the nav label Work is the CV at /work; the portfolio is Projects at /projects. Records published before the projects section existed may still carry /work/* record paths; they render at /projects/* (mapped by src/lib/site-path.ts, with redirects for old URLs).

Setup #

npm install
cp .env.example .env   # then fill in the app password

.env is only needed for publishing (writes). Reads are public: npm run dev and npm run build need no credentials.

Variable Purpose
PDS_URL PDS host, e.g. https://shiitake.us-east.host.bsky.network
ATP_IDENTIFIER DID (or handle) of the account
ATP_APP_PASSWORD App password (create at bsky.app → Settings → App Passwords)

One-time bootstrap (already done for the live site): npm run publish:init creates the publication record, an empty curation record, and publishes the curation lexicon schema.

Writing and publishing a post #

  1. Create a Markdown file in drafts/ with frontmatter:

    ---
    title: "On Field Notes"
    description: "Optional one-line summary, used in listings and meta tags."
    tags: ["note"]
    section: writing
    cover: ./images/on-field-notes-cover.jpg
    date: 2026-07-18
    ---
    
    Body in standard Markdown. Code fences get Shiki highlighting.
    
    Field Required Notes
    title yes
    slug no [a-z0-9-]+ only. Omit for rkey addressing — the minted TID record key becomes the URL slug (/writing/<rkey>, like photography's /photography/<rkey>); author one only when you want a readable URL. URLs are derived from the record's path, whose final segment is the slug (or the rkey). Changing the slug on a later publish creates a new record/URL.
    rkey no 13-char TID record key. Written back into the draft automatically after the first publish of a slug-less draft; from then on it is the update handle for post/status/delete. Hand-editing it to a rkey with no published record creates a record at that rkey.
    description no Listing and OG description
    tags no case-study changes the row CTA on /projects
    section no writing (default) or projects. projects renders under /projects/
    source no Absolute URL to the project's source code, e.g. https://github.com/you/repo. Rendered as a Source link on /projects; omit entirely for none. Relative or malformed URLs are rejected at publish time.
    cover no Path to an image, relative to the draft file. See Images below.
    date no Sets publishedAt on first publish. Omit to use publish time.

    The record's path field stays populated either way — standard.site's verification flow constructs document URLs from site + path, and the site derives its routes from path (src/lib/site-path.ts). Existing posts keep their authored URLs; migrating them to rkey addressing is out of scope.

  2. Publish:

    npm run publish:post drafts/on-field-notes.md
    

    Publishing is an idempotent upsert: keyed on rkey when the draft carries one (added automatically after a slug-less first publish — the CLI prints rkey saved to <draft>), otherwise resolved by the record's path from slug. Run it again after edits and the record is updated in place (publishedAt is preserved, updatedAt is set; a rkey-addressed update keeps the existing record's path verbatim, so a legacy URL never moves). Multiple files can be passed at once.

    Two pitfalls to know: duplicating a draft to start a new post carries its rkey (and slug) with it — clear both before publishing, or the copy updates the original's record instead of creating a new one (the CLI names the record it updated: updated existing record "…"). And removing slug from a draft that was published via the legacy flow mints a fresh rkey and creates a new record/URL — delete the old record if you de-slug an existing post.

  3. Check status of drafts against the PDS:

    npm run publish:status drafts/*.md
    

    Reports new, current, or changed per file.

  4. Rebuild the site (see Deploying) — content is fetched at build time, so a published record is invisible until the next build.

Deleting a post #

npm run delete:post <rkey>              # by record key (the TID written into the draft)
npm run delete:post <slug>              # by slug (path-keyed posts)
npm run delete:post drafts/post.md      # by draft file (rkey or slug read from frontmatter)

Deletes the site.standard.document record from the PDS. Resolution is rkey-first (exact record-key match), with the slug/path match as fallback — so a rkey works even when the record carries a preserved legacy path. Multiple rkeys, slugs, or files can be passed at once. Two things to know:

  • A post pinned in the curation record is refused (a dangling pin fails the next build) — run npm run publish:curation -- unpin <at-uri> first.
  • The draft file is untouched; delete or keep it as you like. Blobs the record referenced become unreferenced and are eligible for PDS garbage collection.

As with publishing, the live site changes on the next rebuild.

Images #

Cover images #

Set cover: in frontmatter to a path relative to the draft file. On publish, the CLI validates the file and uploads it as a blob on the record.

  • Formats: JPEG, PNG, or WebP
  • Max size: 1 MB (MAX_COVER_BYTES) — resize/compress before publishing
  • At build time the blob is downloaded and cached to src/assets/pds/ (gitignored) and rendered through Astro's image pipeline
  • Covers appear on project cards and OG tags. Cards without a cover get a branded fallback, so a cover is optional.

The design portfolio uses the same upload path via npm run publish:curation -- design add --image path/to/file.png ....

Note the -- in every curation example: npm swallows --flags that come before it (with only a warning), so without the separator the flag never reaches the CLI and the record is written without that field.

Inline images in a post body #

Reference images with normal Markdown syntax and a path relative to the draft file, exactly like the cover:

![Antenna array at dusk](./images/antenna.jpg)

On publish:post, the CLI finds every local image reference in the body, validates it (JPEG/PNG/WebP, ≤ 5 MB), uploads it as a blob, and rewrites the reference in the published record to the blob's public getBlob URL. The uploaded blobs are listed in an embeds field on the record, which is what keeps the PDS from garbage-collecting them.

At build time the site downloads each embedded blob into public/pds/ (gitignored) and rewrites the markdown to the self-hosted /pds/<cid>.<ext> copy — the live site never hot-links the PDS, and fixture builds stay offline. Rules and edge cases:

  • Alt text is preserved; always write it.
  • Image references inside code fences or inline code are examples, not embeds — they are left untouched.
  • Remote URLs (https://…) are also left untouched; use them for images hosted elsewhere (e.g. Flickr).
  • Re-publishing re-uploads the bytes; identical bytes produce the same CID, so unchanged images are a no-op on the PDS.
  • publish:status ignores image URL rewrites when diffing, so a published post still reads current.

How images move through the protocol #

Blobs are not records and have no lexicon of their own — they are CID-addressed bytes in the repo's blob store, moved by core com.atproto.* procedures. The only content lexicon involved is site.standard.document:

  1. Upload — com.atproto.repo.uploadBlob (authenticated) sends the bytes and returns a blob ref: $type: "blob", CID, MIME type, size.
  2. Reference — the blob ref is written into the document record via com.atproto.repo.putRecord: coverImage for covers, embeds for inline images. This step matters: the PDS only retains blobs referenced by some record. An uploaded blob nothing points at is eligible for garbage collection.
  3. Read — com.atproto.sync.getBlob?did=…&cid=… serves the bytes publicly, no auth. The build fetches through this endpoint (and caches the result), and it is the URL form stored in published markdown.

Photography #

Photography is published as galleries. The photos, EXIF sidecars, gallery records, and gallery membership (social.grain.photo, social.grain.gallery, social.grain.gallery.item) are all created in the Grain app — this repo never writes them. The curation record then selects which galleries appear on /photography and in what order. Curation is galleries-only: every subject must be a social.grain.gallery AT-URI. An individual photo URI fails the build with "curation photography subject is not a gallery".

To publish a gallery end to end:

  1. In Grain, upload the photos and collect them into a gallery with a title and (optionally) a description and location. The description becomes the statement in the gallery page header; the gallery's first photo is the cover on the /photography index.

  2. Find the gallery's AT-URI: at://<did>/social.grain.gallery/<rkey>. Any atproto record browser (e.g. pdsls.dev) can list the repo's social.grain.gallery records; already-curated URIs show in npm run publish:curation show.

  3. Add it to the curation record (the subcommand is named photo for historical reasons — the subject is a gallery URI):

    npm run publish:curation -- photo add <gallery-at-uri> [--position n] [--feature] [--flickr url]
    npm run publish:curation -- photo move <gallery-at-uri> <position>
    npm run publish:curation -- photo remove <gallery-at-uri>
    

    --feature makes the gallery card span two columns on the index. --flickr adds a "View on Flickr" outlink on the gallery page. Omitting --position prepends: the newest curated gallery leads the page.

  4. Rebuild and deploy (see Deploying).

Gallery detail pages render at /photography/<rkey>/ — all photos in gallery order with EXIF captions, plus title/description/location from the gallery record. Two build-time invariants to know: a curated gallery must contain at least one photo, and the gallery record must still exist on the repo — deleting a gallery in Grain without removing it from curation breaks the next build.

Design portfolio #

Design pieces live only in the curation record (no document record):

npm run publish:curation -- design add \
  --title "Poster Series" --year 2025 --medium "Print" \
  --image path/to/image.png [--description "..."] [--position n]
npm run publish:curation -- design remove "Poster Series"

--title, --year, --medium, and --image are required. The image is uploaded as a blob on the curation record: JPEG/PNG/WebP, ≤ 2 MB. (This cap comes from our own curation lexicon in lexicons/; raising it again means editing the lexicon's maxSize and re-running npm run publish:init to republish the schema. Post covers are capped at 1 MB separately — that limit belongs to the upstream site.standard.document lexicon.)

Unlike photos there is no design move — to reorder, design remove the piece and re-add it with --position. Removal is keyed on the exact title.

Two rendering behaviours on /design worth knowing (src/pages/design.astro):

  • Frames cycle through fixed aspect ratios (3/2, 4/5) for visual variety; images are cropped to fit (object-fit: cover).
  • Pieces whose --medium contains "illustration" or "type", or whose image is a PNG, render uncropped (object-fit: contain) instead — use one of those mediums for posters or layouts where cropping would cut content.

Pinned items #

The home page respects pinned document ordering:

npm run publish:curation -- pin <at-uri>
npm run publish:curation -- unpin <at-uri>
npm run publish:curation -- show     # dump the full curation record

CV #

/work renders from id.sifa.profile.* records (self, position, education, publication, project, skill, presentation, volunteering, ...). There is no publisher command for these; edit the records directly on the PDS with an atproto record tool. Schemas are in src/schemas/sifa.ts. The page doubles as a print resume (print stylesheet hides nav/footer; keep it to 1–2 pages).

Local development #

npm run dev                # dev server against the live PDS
npm run build              # production build → dist/
npm run preview            # serve dist/ locally
npm run build:fixtures     # deterministic build from recorded fixtures (no network)
npm run preview:fixtures   # preview a fixture-backed build
npm run astro -- <cmd>     # any other Astro CLI command (check, sync, ...)

Fixture mode (ASTRO_TEST_FIXTURES=1) swaps the XRPC client for one backed by tests/fixtures/recorded/*.json and makes zero network requests. After publishing content that tests depend on, refresh fixtures with node tools/record-fixtures.mjs and review the diff before committing.

Testing #

npm test                   # Vitest unit/integration (includes a full build check)
npm run test:e2e           # Playwright E2E + visual regression (builds with fixtures)
npm run test:e2e:ui        # Playwright interactive mode
npm run test:e2e:report    # open the last HTML report

See docs/CONTRIBUTING_E2E.md for fixture format, baseline policy, and troubleshooting. Visual baselines are platform-suffixed; never update a baseline without reviewing it against scarnecchia-design-kit/. If the E2E web server complains port 4321 is taken, kill the stale preview: lsof -ti :4321 | xargs kill.

Deploying #

The build output is plain static files — any static file server works. Today, deployment is manual:

npm test && npm run test:e2e   # verify
npm run build                  # fetches live PDS content → dist/
# copy dist/ to the web server

Because content is fetched at build time, every content change needs a rebuild and redeploy — publishing a record alone does not update the live site.

An automated pipeline is planned but not yet implemented (see docs/implementation-plans/2026-07-18-scarnecchia-site/phase_05.md): the site will run on the k3s node behind the existing Caddy proxy, with a watcher consuming Jetstream that triggers a rebuild Job whenever site records change on the PDS, plus a daily rebuild as a safety net. Once that lands, publishing a record is the whole deploy.

Repo map #

drafts/            Markdown drafts (source of truth stays on the PDS once published)
lexicons/          Published lexicon schemas (contracts — coordinate changes)
src/pages/         Routes (index, writing, projects, design, photography, work, rss, 404)
src/loaders/       Astro content-layer loaders that fetch PDS records at build
src/schemas/       Zod schemas for every record type
src/lib/           Pure logic: XRPC client, path mapping, EXIF, dates
src/styles/        Design tokens, Vignelli grid, nav, print, sidenotes
tools/publisher/   The publish CLI (post / delete / curation / status / init)
tools/record-fixtures.mjs  Refresh recorded PDS fixtures
tests/             Vitest + Playwright suites and fixtures
docs/              E2E contributing guide, implementation plans
scarnecchia-design-kit/    Design reference specimen (read-only)

Deeper conventions, invariants, and agent guidance: AGENTS.md.