Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Everything is owned and reviewed by the site owner.
# Content changes especially require a review pass for sanitization before merge.
* @Grashopr-888

# Sensitive surfaces — never merge without an explicit sanitization review.
/src/content/ @Grashopr-888
/scripts/ @Grashopr-888
/src/data/ @Grashopr-888
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: What this repo is
url: https://github.com/Grashopr-888/current-projects#readme
about: Read the README before filing — this is a sanitized process showcase, not the products' source.
35 changes: 35 additions & 0 deletions .github/ISSUE_TEMPLATE/content-update.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: Content update
description: Add or revise a project, decision, release, incident, research note, or milestone.
labels: [content]
body:
- type: dropdown
id: collection
attributes:
label: Collection
options:
- projects
- decisions
- releases
- incidents
- research
- milestones
- changelog
- glossary
validations:
required: true
- type: textarea
id: change
attributes:
label: What should change
description: Describe the entry to add or edit. Link the source of truth if there is one.
validations:
required: true
- type: checkboxes
id: sanitization
attributes:
label: Sanitization
options:
- label: This exposes no private source, secrets, corpus, or in-progress paper results
required: true
- label: No collaborator is identified without consent
required: true
31 changes: 31 additions & 0 deletions .github/ISSUE_TEMPLATE/new-project.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: New project
description: Add a third (or later) project to the showcase.
labels: [content, new-project]
body:
- type: input
id: slug
attributes:
label: Project slug
description: kebab-case; becomes the URL and the value added to PRODUCTS in content.config.ts.
placeholder: my-new-project
validations:
required: true
- type: textarea
id: thesis
attributes:
label: Thesis & problem
description: One line each — the bet, and the problem it addresses.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Sanitized evidence available
description: Which decisions, releases, incidents, and research can be shown as process?
- type: checkboxes
id: sanitization
attributes:
label: Sanitization
options:
- label: Source stays private; only process artifacts will be published
required: true
27 changes: 27 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!-- Keep this honest — the repo's whole point is disciplined, sanitized process. -->

## What & why

<!-- One or two sentences. What changed, and what it improves. -->

## Type

- [ ] Content (new/edited project, decision, release, incident, research, milestone)
- [ ] Site (components, layout, styles)
- [ ] Pipeline (ingestion / redaction scripts)
- [ ] Ops (CI, deploy, config, docs)

## Sanitization check (required for any content or pipeline change)

- [ ] No private source code, secrets, tokens, or internal hostnames
- [ ] No proprietary corpus, model weights, or in-progress paper results
- [ ] No collaborator identified without their consent
- [ ] `npm run redact:check` is clean
- [ ] Anything sensitive is summarized a level up, not pasted verbatim

## Quality

- [ ] `npm run check` (type-check) passes
- [ ] `npm run build` passes
- [ ] `npm run format` applied
- [ ] Reads in the site's register: calm, specific, not self-congratulatory
23 changes: 23 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
version: 2
updates:
- package-ecosystem: npm
directory: '/'
schedule:
interval: weekly
open-pull-requests-limit: 5
groups:
astro:
patterns:
- 'astro'
- '@astrojs/*'
dev-tooling:
patterns:
- 'prettier*'
- 'typescript'
- 'tsx'
- '@types/*'

- package-ecosystem: github-actions
directory: '/'
schedule:
interval: weekly
37 changes: 37 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: CI

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
verify:
name: typecheck · format · build · redact
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7

- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm

- name: Install
run: npm ci

- name: Type-check (astro check)
run: npm run check

- name: Format check (prettier)
run: npm run format:check

- name: Build
run: npm run build

- name: Redaction gate (no secrets in published content)
run: npm run redact:check
37 changes: 37 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: Deploy to GitHub Pages

on:
push:
branches: [main]
workflow_dispatch:

# Allow one concurrent deployment; don't cancel an in-progress production deploy.
permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
# Installs deps, runs `astro build`, and uploads the Pages artifact.
# `site` / `base` come from astro.config.mjs — no need to pass them here.
- uses: withastro/action@v3

deploy:
name: Deploy
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
43 changes: 43 additions & 0 deletions docs/admin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Admin — branch protection, Pages, rollout

## Branch protection (recommended for `main`)

In **Settings → Branches → Add rule** for `main`:

- Require a pull request before merging (1 approval).
- Require status checks to pass: the **CI** workflow (`typecheck · format · build · redact`).
- Require branches to be up to date before merging.
- Require review from Code Owners (enforces `CODEOWNERS`).
- Do not allow bypassing the above.

This makes the redaction gate and the type-check unskippable — you cannot merge content that
leaks a secret or breaks a cross-reference.

## GitHub Pages setup

1. **Settings → Pages → Build and deployment → Source: GitHub Actions.**
2. Push to `main`. The [`deploy.yml`](../.github/workflows/deploy.yml) workflow builds with
Astro and publishes.
3. The URL is `https://<owner>.github.io/<repo>/`. Keep `site`/`base` in
[`astro.config.mjs`](../astro.config.mjs) in sync with it.

### Custom domain

Set `site` to your domain and `base` to `/` in `astro.config.mjs`, add a `public/CNAME`
containing the domain, and configure the domain in **Settings → Pages**.

## Private-first, public-later rollout

A GitHub Pages site is **publicly reachable by default**, even from a private repo — private
Pages access control requires GitHub Enterprise Cloud. So treat "the repo is private" as **not**
equivalent to "the site is private."

Safe rollout:

1. Build and iterate while the repo is private and **Pages is not enabled** (or deploy only to
a non-public preview).
2. Run the [publishing checklist](publishing-checklist.md) — `redact:check` clean, every
content change read by a human for sanitization.
3. Only then enable Pages / make the repo public.

Never assume privacy from repo visibility alone.
47 changes: 47 additions & 0 deletions docs/content-model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Content model

Everything on the site is typed data, defined in
[`src/content.config.ts`](../src/content.config.ts) and stored as Markdown under
`src/content/`. Cross-references are validated at build time — a dangling link fails the
build, so the narrative can't drift from the data.

`product` is one of `windchime`, `lichtspiel`, `shared`. Add a project by adding its slug to
`PRODUCTS`.

## Collections

| Collection | One entry is… | Notable fields |
| ------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `projects` | A product hub | `thesis`, `problem`, `audience`, `constraints[]`, `outcomes[]`, `tech[]`, `status`, `public_visibility_note` |
| `decisions` | An ADR | `context`, `options_considered[]`, `decision`, `rationale`, `consequences`, `status` |
| `releases` | A shipped (or planned) release | `version_or_label`, `customer_value`, `included_work[]`, `notable_risks[]`, `linked_incidents[]` |
| `incidents` | A blameless postmortem | `severity`, `impact`, `detection`, `root_cause`, `fix`, `followup_actions[]`, `blameless_note` |
| `milestones` | A roadmap item | `horizon` (now/next/later/shipped), `theme`, `status`, `confidence`, `linked_releases[]` |
| `research` | A sanitized research note | `source_type`, `questions[]`, `insights[]`, `implications[]`, `redaction_status` |
| `changelog` | A changelog line | `category`, `linked_release`, `linked_project` |
| `artifacts` | A screenshot/diagram/doc | `type`, `media`, `alt`, `caption`, `redaction_status` |
| `glossary` | A term | `term`, `definition`, `related[]` |

## Cross-references

`reference('<collection>')` fields (e.g. `linked_release`, `linked_incidents`,
`related_decisions`) must resolve to an entry `id` (its filename without extension). Example:

```yaml
# in a release
linked_incidents:
- wc-audio-runaway # → src/content/incidents/wc-audio-runaway.md must exist
```

## Provenance & redaction fields

`research` and `artifacts` carry `provenance` and `redaction_status`
(`clean` | `sanitized` | `needs-review` | `placeholder`). The ingestion pipeline writes
`needs-review` candidates; a human clears them before promotion.

## How pages consume it

Project pages query by `product`; the aggregate pages (Roadmap, Releases, Research,
Incidents) query across products. Query helpers live in
[`src/lib/content.ts`](../src/lib/content.ts); the sanitized git activity is read by
[`src/lib/signals.ts`](../src/lib/signals.ts).
43 changes: 43 additions & 0 deletions docs/editorial-guidelines.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Editorial guidelines

The site itself is evidence of product taste and judgment. Write like it.

## Register

Calm · precise · reflective · technically literate · product-minded · **not**
self-congratulatory.

Every major page should answer: **what is this, why does it matter, what happened, what
changed?** Surface role, constraints, and outcomes early. Design for skimming first, deep
reading second.

## Do

- Lead with the problem and the trade-off.
- Be concrete: name what was measured, what shipped, what broke, what changed after.
- Use timelines, cards, and short synthesis over dense paragraphs.
- Say the "no" out loud — what a product deliberately is _not_.
- When something is sensitive, summarize the class of decision and what was learned.

## Don't

- Buzzword-stuff or inflate ("revolutionary", "cutting-edge", "10x").
- Claim vague leadership ("led cross-functional teams") without evidence.
- Write walls of text.
- Dead-end on "confidential, can't say more" — summarize a level up instead.
- Name a collaborator without their consent.

## Structure conventions

- **Projects** — thesis and problem up top; narrative in the body; typed records
(decisions/releases/incidents/research) below; outcomes last.
- **Decisions** — context → options with honest trade-offs → decision → rationale →
consequences.
- **Incidents** — impact → detection → root cause → fix → follow-through → blameless note.
- **Releases** — frame by customer value and risk, not the diff.

## Numbers

Prefer exact figures when they're safe engineering/ops metrics (soak hours, corpus size,
commit counts). Keep confidential figures in bands, or omit. Never publish results from
work still under review — show the method instead.
52 changes: 52 additions & 0 deletions docs/publishing-checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Publishing checklist — private → public

Run this before enabling GitHub Pages or making the repo public, and again before any release
that adds content derived from private work. The automated gate is necessary but **not
sufficient** — a human must read every content change.

## 1. Automated gates (must all pass)

```bash
npm run check # types + cross-references resolve
npm run build # production build succeeds
npm run format:check # formatting is clean
npm run redact:check # no secrets, hosts, emails, or large code blocks in src/content
```

Also confirm nothing sensitive rode into the sanitized snapshots:

```bash
npm run redact:check src/data/snapshots
```

## 2. Human sanitization review

Read every added/changed entry and confirm it exposes **none** of:

- [ ] Source code, or architecture detail specific enough to reconstruct it
- [ ] Secrets, tokens, API keys, internal hostnames, ports, or env values
- [ ] Proprietary corpus, sample libraries, or model weights
- [ ] In-progress academic results, a paper's claims, or a blind-review venue
- [ ] A collaborator's name or identity without their explicit consent
- [ ] Personal data (transcripts, user records) from studies or runtime logs

## 3. Staging hygiene

- [ ] `.private/` is gitignored and contains no committed files (`git status` is clean of it)
- [ ] No `.env` or `*.raw.json` is staged
- [ ] Screenshots/diagrams are at the system-boundary level; no sensitive UI or data visible

## 4. Framing & accuracy

- [ ] Project names, venues, and collaborators are stated accurately
- [ ] Numbers are safe to publish (ops/engineering metrics, not confidential results)
- [ ] Copy reads in register — calm, specific, not self-congratulatory
- [ ] The owner's real name is set in `src/config.ts` (or intentionally left as handle)

## 5. Platform

- [ ] You understand a Pages site is public by default (see [admin.md](admin.md))
- [ ] `site` / `base` in `astro.config.mjs` match the deploy target
- [ ] Branch protection requires the CI check before merge to `main`

Only when every box is checked: enable Pages / flip the repo public.
Loading
Loading