initial flashtrace public + documentation website

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # mirrors the build job of deploy.yml (minus the dispatch payload, which
+  # only exists on releases) so a green check means the deploy build passes
+  # on the same inputs - keep the two in sync
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      # An empty tag would make the checkout below silently use the default
+      # branch, so fail loudly instead - same guard as in deploy.yml.
+      - name: Resolve flashtrace release ref
+        id: ref
+        run: |
+          tag=$(gh release view --repo flashtrace/flashtrace --json tagName --jq .tagName) || true
+          if [ -z "$tag" ]; then
+            echo "::error::no release tag: flashtrace/flashtrace has no published release"
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: flashtrace/flashtrace
+          ref: ${{ steps.ref.outputs.tag }}
+          path: flashtrace
+
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+        env:
+          FLASHTRACE_REF: ${{ steps.ref.outputs.tag }}
+
+      # also exercised here so artifact packaging failures surface in CI,
+      # not first during a deploy
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist
+          retention-days: 1

.github/workflows/deploy.yml

@@ -0,0 +1,80 @@
+name: Deploy site
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+  # fired by flashtrace/flashtrace's release workflow after every release,
+  # with client_payload.tag = the new release tag
+  repository_dispatch:
+    types: [flashtrace-release]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      # docs are built from the released tool, not its main branch: take the
+      # tag from the dispatch payload, or fall back to the latest release.
+      # An empty tag would make the checkout below silently use the default
+      # branch, so fail loudly instead.
+      - name: Resolve flashtrace release ref
+        id: ref
+        run: |
+          tag="$RAW_TAG"
+          if [ -z "$tag" ]; then
+            tag=$(gh release view --repo flashtrace/flashtrace --json tagName --jq .tagName) || true
+          fi
+          if [ -z "$tag" ]; then
+            echo "::error::no release tag: dispatch payload was empty and flashtrace/flashtrace has no published release"
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+        env:
+          # env, not inline ${{ }}: the dispatch payload is untrusted input and
+          # must reach the shell as data, never as script text
+          RAW_TAG: ${{ github.event.client_payload.tag }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          repository: flashtrace/flashtrace
+          ref: ${{ steps.ref.outputs.tag }}
+          path: flashtrace
+
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+        env:
+          FLASHTRACE_REF: ${{ steps.ref.outputs.tag }}
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+flashtrace/

CLAUDE.md

@@ -0,0 +1,64 @@
+# Agent Guide
+
+This repository contains the representative and documentation website for [flashtrace](https://github.com/flashtrace/flashtrace), a "lightning-fast, reference-based requirement tracing" suite.
+In the following you will be introduced to some helpful structural guidance as well as hard constraints.
+
+First of all:
+Work professionally, remember to use modern day best practices and stay focused.
+Feel free to tell a user when their tasks seems unscoped or ambiguous.
+Ask refining questions before you start writing.
+
+## The Repository Structure
+
+| Folder | Purpose |
+|---|---|
+| src/ | Source code, used from 'build.mjs' to create 'dist/' |
+| public/ | Assets that should be included exactly as they are in the final 'dist/' |
+| dist/ | Uncommitted, generated build output |
+| flashtrace/ | Uncommitted, gitignored clone of [flashtrace/flashtrace](https://github.com/flashtrace/flashtrace); its 'docs/' are a required build input |
+| .github/ | Continuous integration/deployment workflows |
+
+'build.mjs' renders the tool repo's 'docs/' into the site, so a build needs access to them.
+It looks for the docs at `$FLASHTRACE_DOCS`, then './flashtrace/docs', then '../flashtrace/docs' - if none exist, clone the tool repo first: `git clone https://github.com/flashtrace/flashtrace`.
+
+Keep dev dependencies to a minimum.
+Keep (runtime) dependencies to zero.
+
+## The Commands
+
+| Cmd | Purpose |
+|---|---|
+| `pnpm build` | Build the website with 'build.mjs' (which is using 'src/' and 'marked' being the sole dependency) into 'dist/'. |
+| `pnpm dev`   | Live-rebuilds on changes and serves the website from 'dist/' for local testing. |
+| `pnpm clean` | Wipes 'dist/' gracefully. |
+
+## Your workflow
+
+Work in small chunks.
+Commit regularly on proper (preliminary) results.
+Follow conventional commits, that means use the format `<type>: <short description of work>` for every commit.
+You can add a descriptive body too.
+Adapt a similar pattern for branch naming.
+
+We are using merging over Pull Requests from feature-branches.
+Every PR is being merged in as a commit; we do not squash the commits nor do we rebase anything directly on top of main without a merge commit.
+Remember to have one branch focused on one change.
+Suggest to split into multiple if applicable.
+
+`dist/` stays uncommitted, it should however always be buildable without issues before committing any source.
+Note that the output can change without any local changes, as this also depends on `flashtrace/flashtrace`'s version.
+On production of this website, this is automatically updated through the `deploy.yml` workflow being dispatched from the release workflow of `flashtrace/flashtrace`.
+
+We do NOT maintain a `package.json` version here, as this repository is not published as a package anywhere; deployments happen on either a merge into main or automatically on a new `flashtrace/flashtrace` release (to update the docs and versioning).
+
+## Parallel work with git worktrees
+
+One task = one branch = one worktree = one session.
+All rules apply unchanged inside every worktree.
+
+- Create worktrees as siblings of the main checkout: `git worktree add ..\flashtrace.github.io-wt\<branch-dir> -b <type>/<description> origin/main`
+- Run `pnpm install` in a fresh worktree before building or testing; node_modules is per-worktree (pnpm's store makes this fast).
+- The flashtrace clone is not shared into worktrees ('../flashtrace' resolves to the worktree's parent, not the main checkout). Point `FLASHTRACE_DOCS` at the main checkout's clone (e.g. `$env:FLASHTRACE_DOCS = "C:\your\path\to\flashtrace.github.io\flashtrace\docs"`) or clone it next to the worktree before building.
+- Branch only from up-to-date `origin/main`. Never commit to `main`, and never check out or modify a branch owned by another worktree.
+- Before opening a PR: Verify `pnpm build` passes.
+- After your PR merges: `git worktree remove <path>` and delete the branch.

README.md

@@ -0,0 +1,41 @@
+# flashtrace.github.io
+
+The website of [flashtrace](https://github.com/flashtrace/flashtrace) - a landing page plus
+documentation rendered from the tool repository's `docs/`, served by GitHub Pages at
+[flashtrace.github.io](https://flashtrace.github.io/).
+
+Built in the flashtrace spirit: plain static HTML/CSS/JS, no runtime framework, and a single
+build-time dependency ([marked](https://github.com/markedjs/marked)).
+
+## How it works
+
+- `build.mjs` reads the tool repository's `docs/` (nav order derived from `docs/index.md`),
+  renders every page through `marked`, rewrites inter-doc links to clean URLs and emits a
+  fully static site into `dist/`.
+- The landing page (`src/landing.mjs`) is hand-written HTML: a CSS-only IDE mock in the hero,
+  feature grid, curated interactive examples (`src/examples.mjs`, captured from real
+  `flashtrace` runs) and the install snippets.
+- `.github/workflows/deploy.yml` builds and deploys on every push to `main`, on manual
+  `workflow_dispatch`, and on a `repository_dispatch` of type `flashtrace-release` that the
+  tool repository fires after each release. Docs are always checked out at the release tag
+  (from the dispatch payload, or the latest release otherwise) - the site documents released
+  behavior, not `main`.
+
+## Local development
+
+```sh
+git clone https://github.com/flashtrace/flashtrace ../flashtrace   # docs source, once
+pnpm install
+pnpm build          # emits dist/
+pnpm dev            # build + watch + serve on http://localhost:8788
+```
+
+The docs directory is resolved in this order: `$FLASHTRACE_DOCS` → `./flashtrace/docs`
+(the CI checkout location) → `../flashtrace/docs` (local sibling checkout). Set
+`FLASHTRACE_REF` to override the version label rendered in the header and footer.
+
+`dist/` is never committed; CI builds it fresh on every deploy.
+
+## License
+
+[Apache 2.0](LICENSE), like flashtrace itself.