Know This Place

A map-less (for now), crowd-editable encyclopedia of the built environment — one rich, Wikipedia-style page per building, starting with the Castro / Eureka Valley neighborhood of San Francisco. Live at https://knowthis.place.

How it works

There is deliberately no CMS, no database, no build framework:

• Content is a geographic tree of directories. Each address holds data.json (the single source of truth — structured facts with citations, plus any prose in a narrative field), assets/ (openly licensed media), and index.html (the generated page). Keeping facts and prose in one file means the two can't drift into conflict.
• index.html is a build artifact, not a template render at request time. Pages are composed from a shared design system — a CSS component library (shared/site.css) of stat tiles, a visual timeline, charts, and icons, plus a tiny progressive-enhancement layer (shared/site.js: web components for the Street View still, the Mapbox locator map, and chart tooltips). The JS only enhances — every page renders completely from its HTML alone, so pages stay static and crawlable. Consistency is enforced by a small contract checked in CI — see shared/AGENTS.md and scripts/validate.py.
• A page is seeded once, then its data.json is edited forever after. scripts/seed_pages.py joins the DataSF datasets and writes the first data.json + index.html for every parcel that has no page yet; seed never returns to a page it has written, so a second run creates nothing. Everything after that first draft (corrections, research, a building's story, reader feedback) is a person or an agent editing data.json and re-running seed_pages.py render <path>, which rewrites the HTML from the data in place. Nobody edits index.html: validate.py fails if a page's HTML is not exactly what the renderer produces from its data.json, which is what keeps the two from drifting.
• Agents do the work a CMS would. Rules live in AGENTS.md files through the tree; the live city APIs are cataloged in DATA-SOURCES.md.
• Finding things to say is a separate job from saying them. Newspaper archives, books, newsletters and survey PDFs — the sources that make a page worth landing on — are mined in the research module, which hands the site verified, sourced facts. Building the site and researching it are deliberately kept apart.
• What happens at an address today is watched by the news module. It polls the city's newsrooms, keeps a cursor per feed, and puts the stories that name a building onto that building's timeline — the one thing an indexed news archive doesn't do for itself.

The editing loop

1. Every page footer links to a prefilled GitHub issue form (.github/ISSUE_TEMPLATE/page-feedback.yml). Readers describe a change in plain words; the form carries the page path.
2. The issue triggers Claude Code in GitHub Actions (.github/workflows/feedback-agent.yml), which verifies the claim against sources, updates data.json / assets/, re-renders index.html from it, and opens a pull request that closes the issue.
3. A human reviews and merges through normal GitHub PR review. Merging to main is the deploy — .github/workflows/deploy.yml builds the site from the merged sources and publishes it to GitHub Pages.
4. A scheduled workflow (.github/workflows/refresh.yml) periodically re-queries time-sensitive data (permits, assessments, news).

Repo layout

CLAUDE.md                     The map: which file to read for which job
AGENTS.md                     Agent constitution — the rules core
REFERENCE.md                  data.json schema, page types, seeding, the
                              reasoning behind the rules
DATA-SOURCES.md               Catalog of live city APIs agents draw from
index.html                    Site homepage — the one hand-written page
san-francisco/
  castro/
    AGENTS.md                 Neighborhood-specific guidance
    <street-slug>/<number>/   One directory per building (see AGENTS.md)
  historic-districts/<slug>/  One page per historic district — the buildings
                              inside it and the streets it runs through,
                              generated by `seed_pages.py districts`
shared/
  AGENTS.md                   The page contract: hard rules, key → block map
  BLOCKS.md                   The block library — what the renderer produces
  site.css                    The only stylesheet (component library)
  site.js                     Enhancement layer (progressive web components)
  site-config.json            Site URL, repo URL, Maps embed key,
                              Mapbox token
research/
  AGENTS.md                   Research rulebook: the run and its rules
  RUNBOOK.md                  The procedure for a run, step by step
  LESSONS.md                  147 traps that already cost a session — grep it
  SOURCES.md                  Register of every source mined, and leads
  TRIAGE.md                   What a prospecting pass found, per held lead
  sources/<id>.md             One dossier per source: access, cautions,
                              coverage log
  findings/                   The chain of custody, one file per batch
  schema/                     The findings JSON schema + a worked example
  manifests/                  Parcel lists produced here, seeded by the script
  tools/check.py              Research consistency checks (stdlib only)
news/
  AGENTS.md                   News rulebook: what an entry is, privacy
  PIPELINE.md                 Per-stage detail: cursors, the screen, the markup
  feeds.json                  Register of every feed, and how each misbehaves
  state/cursors.json          What each feed has been considered up to
  queue/<date>.json           One poll run: what to read, what was skipped, why
  items/<feed>/*.json         Findings files — research schema, research resolver
  tools/poll.py               Fetch, screen, queue, advance the cursors
  tools/read.py               Read queued articles; report the addresses in them
design/
  AGENTS.md                   Design module entry: direction of truth, layers
  PRINCIPLES.md               Portable design judgement
  CONVENTIONS.md              How design work is done in this repo
  PAPER.md                    paper.design tool quirks
  IMPLEMENTATION.md           Tokens, type, rem→px, metrics, icons
  RULES-OF-THUMB.md           Generated: the distilled corpus
  META.md / GAPS.md           Learning notes; cases /ui had to guess at
scripts/
  build_site.py               The build: every generator below, in the one
                              order that works. Actions runs it on deploy
  seed_pages.py               Writes the first draft of pages that don't
                              exist yet, from the DataSF APIs; `render`
                              rewrites a page's index.html from its data.json
  permit_redactions.json      Names stripped from permit text before it's saved
  validate.py                 CI contract checks (stdlib only)
  build_sitemap.py            Regenerates sitemap.xml (a sitemap index)
                              and sitemaps/ — one child per neighborhood
  build_map_index.py          Regenerates shared/addresses.geojson
  build_link_index.py         Regenerates shared/nearby.json — each
                              page's nearby pages, for lateral links
  build_corpus_index.py       Regenerates corpus.jsonl — one line per
                              address page, for corpus-wide questions
  build_stats.py              Regenerates the dashboard at /stats/
corpus.jsonl                  One line per address page — path, year, use,
                              district, earliest date, sources, hook. Derived,
                              but committed, so a corpus-wide question costs
                              a grep rather than a build
.github/
  ISSUE_TEMPLATE/page-feedback.yml
  workflows/{deploy,feedback-agent,news,refresh,validate}.yml

None of the site is in that tree. Every index.html under san-francisco/, sitemap.xml, sitemaps/, shared/addresses.geojson, shared/nearby.json and stats/index.html are built from the files above and gitignored; the repository is 18,013 tracked files rather than 35,688 because of it. REFERENCE.md → The site is built, not committed has the reasoning and the two exceptions.

Running it locally

python3 scripts/build_site.py --serve     # build, then http://localhost:8517

Nothing to install — Python 3.9 and the standard library. The build takes about a minute; --no-build --serve skips it and serves what is already there. Use port 8517 and no other: the Mapbox token and the Google Maps embed key are URL-restricted to it, so the maps only render there.

Setup checklist (Phase 0)

• Push to GitHub; confirm repo_url in shared/site-config.json
• Settings → Pages → Build and deployment → Source: GitHub Actions (not "Deploy from a branch" — the branch holds no pages); custom domain knowthis.place
• DNS: apex A/ALIAS records → GitHub Pages, per GitHub docs (CNAME file is committed)
• Add ANTHROPIC_API_KEY Actions secret; install the Claude GitHub App for this repo
• Settings → Actions → General → check "Allow GitHub Actions to create and approve pull requests" (off by default; without it the agent can't open PRs)
• Create the page-feedback label (Issues → Labels → New label). GitHub silently ignores labels an issue form references but that don't exist, which leaves feedback issues unlabeled and the agent workflow skipped.
• Branch protection on main: require PR review (you)
• Create a Google Maps Embed API key, referrer-locked to knowthis.place, and put it in shared/site-config.json
• Create a Mapbox public token (pk.…) for the homepage map and the per-page locator maps, URL-restricted to knowthis.place and http://localhost:8517, and put it in shared/site-config.json as mapbox_token. Address pages request one Static Images call per view, so watch the account's monthly request count as coverage grows
• Verify each endpoint in DATA-SOURCES.md with a live query and fill in its Verified: date
• Verify the property in and submit . It is a sitemap index, so submitting it registers all 43 children; Search Console then reports coverage per child, which is the only per-neighborhood indexation number the site has. Resubmit only if the entry point ever moves — new children are picked up from the index

Seeding a neighborhood

python3 scripts/seed_pages.py plan --neighborhood "Castro/Upper Market"
python3 scripts/seed_pages.py seed --neighborhood "Castro/Upper Market" \
                                   --city san-francisco --area castro
python3 scripts/build_site.py
python3 scripts/validate.py

plan reports what would be written and why parcels are skipped; seed writes the new pages and rebuilds the street hubs. seed only ever creates — it skips any address that already has a page, so re-running it is safe and is a no-op unless new parcels have appeared. Raw dataset rows are cached in .cache/ (gitignored) and each fetch resumes where it left off, so an interrupted run is cheap to restart. --neighborhood takes the SF Planning analysis-neighborhood name as it appears in the datasets.

Researching

python3 research/tools/check.py --stats

The research module is where sources are found, mined and turned into citable facts. It runs on files rather than conversations — a register, a dossier per source, structured findings, and GitHub issues — so a scan that takes six sessions across three agents doesn't lose its place. Start at research/AGENTS.md, and grep research/LESSONS.md for whatever you are about to do.

The bias is toward sources search engines can't see: newspaper OCR, out-of-print books, neighborhood newsletters, PDF survey reports. A pass that reads a whole book and yields four citable facts is a good pass.

Watching the news

python3 news/tools/poll.py poll                 # every open feed
python3 news/tools/poll.py status               # where the cursors stand
python3 news/tools/read.py news/queue/<date>.json

The news module runs daily in CI (.github/workflows/news.yml) and asks a different question from research: not what has never been written about this address, but what was written about it this week. Nine feeds, a cursor apiece, a cheap screen that throws out the Oakland stories and the ones that could not be about a building, and a reader's judgement on the rest. A handful of buildings a day survive that, and most of them have no page yet — 10,828 pages is a small slice of the city — so the module seeds the parcel and puts the story on the page it just made. Start at news/AGENTS.md.

Running the agent locally

Any Claude Code session in this repo picks up CLAUDE.md automatically — a one-page map that routes to the rules core for the job at hand. Use an agent for the work a script can't do — verifying a reader's feedback, researching a building's history, writing the prose for a page that has a story — not for seeding pages from city data.