# Website maintenance guide

Current authority (2026-10-05): the owner authorized Cloudflare publication while keeping the source repository private. Primary public URL: [https://security.devsatym.xyz](https://security.devsatym.xyz). Custom-domain DNS and HTTPS were verified at `2026-10-04T23:38:38.482202Z`: Pages domain, verification and certificate-validation statuses were active, and a real HTTPS request returned200 with TLS verification result0. The owner added `CNAME security → gcp-security-handbook.pages.dev`; direct authoritative launch1/launch2 and recursive1.1.1.1 queries confirmed it. One documented Pages validation retry was performed; no agent DNS, nameserver, billing or unrelated-record writes were made. Custom-origin build, metadata and hosted verification results are recorded separately in excluded audit receipts. DNS/TLS activation and historical Pages checks do not establish those artifact results. Earlier48d/f88 pages.dev native/browser/HTTP and CI checkpoints remain preserved in excluded audits; they are not new custom-origin results. Keep production main and automatic branch previews. Use runbook09 and internal record14 for settings/receipts; preserve billing, nameservers, unrelated DNS and the original application repository.

## Keep the two systems separate

The handbook source lives in the separate private `devSatym/gcp-security-handbook` repository; engineering files describe this static website. The public-facing content describes the historical GCP system in `devSatym/gcp-supply-chain-security`, whose reviewed main is Azure. Updating handbook prose does not authorize changes to that source project or its cloud controls. New implementation claims must name their source revision/edition rather than silently blending it into GCP content.

## Add or edit a page

Place Markdown/MDX under the appropriate `src/content/docs/` group. Supply required title/description/documentType/audience/baseline/reviewDate/status and arrays for controls, sources, evidence, prerequisites, related. Choose a type based on reader purpose and a status based on actual implementation classification. A review date is editorial, not a capture date.

Introduce the question, concrete failure, exact implementation, verification/evidence boundary, and limitations. Use pinned full-SHA sources. Reuse `SecurityContract`, `SourceReference`, `EvidencePanel`, or `Diagram` where they clarify a claim; read their actual prop contracts. Avoid unknown IDs or copying generic marketing claims. An operational command must state whether it is local, cloud-read, mutating, or destructive; do not include shell prompts.

For a renamed route, update sidebar directory implications, reading paths, stage/control routes, prerequisites/related metadata, and ordinary Markdown links. Run content checks followed by production build/output audit. Search reflects production text; test a representative new term through Pagefind.

## Add a source, control, stage, or evidence record

Use the Zod contracts in `src/lib/schemas.mjs` and aggregation in `src/data/catalogue.ts`. IDs are stable keys rather than prose headings. Source records require repository, full commit, path, URL, hash, inspection status/date, and symbol/kind context. Inspect the actual snapshot; hashing alone does not interpret behavior.

A control requires its question, property, inputs/outputs, authority dependencies, scope/exclusions, failure behavior, limits, source IDs, concept routes, stage IDs, and evidence mapping. A stage names the handoff and verifier. Update both sides of any control/evidence association.

Evidence requires origin, environment, category, actual/expected observation, transcript, original source, limitations, and publication approval. Set `originalPath` to a known baseline source and bind `originalReference` to its exact repository/full-SHA/path; a mutable branch URL is rejected. Unknown date/revision stays null. Preserve originals; create a reviewed derivative only when necessary, record its redaction/cropping, dimensions, and provenance. Do not turn a hypothetical test into recorded execution. A screenshot of the website is UI-test evidence, not cloud-control evidence.

## Add a diagram or public report

Add a diagram record with stable ID, title, caption, four sequence nodes, explanatory steps, and semantics. Ensure visual labels fit and the text equivalent preserves meaning. The current renderer generates accessible SVG at build time; there is no Mermaid runtime to configure. Avoid repeating the same diagram ID twice on a page without implementing per-instance SVG IDs.

Public report filenames are explicitly allowlisted by asset preparation. Create a sanitized derivative, review links and disclosure risks, then add it to the allowlist and publication checks. Do not copy the complete `engineering/` directory into public output. Keep ledgers, raw logs, diagnostics, operational state, and local paths private to the workspace/internal artifact.

## Update the source baseline deliberately

Resolve any proposed tag to its underlying commit. Record old/new full source SHA, edition, evidence-source revisions, inspection date, and review date separately. Inspect execution paths again; old comments and old capture captions may no longer describe behavior. Recompute source hashes, revise coverage, catalogue source links, control scope, and evidence mapping.

Historical evidence remains tied to its capture/revision context. Do not relabel it as a result from the new revision. Maintain a clear boundary if another edition is introduced. Changes to active cloud implementation are outside this website maintenance process.

Use `SOURCE_REPO_PATH` for the explicit source-hash audit against a separate checkout containing the baseline objects. Keep that input read-only and outside the handbook's new Git history. Source/evidence URLs retain the original repository and full SHA; edit links target the handbook's main branch. Do not copy current application workflows into the documentation repository.

## Dependencies and recurrent checks

Use `npm ci` for clean installation. For dependency updates, review primary release/API documentation, regenerate the intentional lockfile, inspect audit results, and run the meaningful validation chain. Major Astro/Starlight changes can alter schemas, layout overrides, search paths, and static route output. Update as-built docs and browser tests together.

Review stale content when source baselines, vendor contracts, captured assumptions, or deployment settings change; no automatic recurring schedule is created by this guide. Preserve review dates and record actual source inspection. Performance targets remain lab targets, not guarantees after future updates.

## Troubleshooting and final reconciliation

An unknown ID is a data/authoring defect; repair the record/reference rather than suppressing the exception. A broken base-path asset is a routing defect; inspect helper use and generated output. Search missing in development requires production build verification before diagnosis. A report leak requires removing the unapproved public derivative, reviewing output, and recording the disclosure handling; deleting the audit does not repair it.

After every release of the handbook, update requirements traceability, audits, and final-report status with actual outcomes, then rebuild/audit the final public output. Leave remote publication and hosted verification clearly separate from local completion.

Keep original/migration and `199e811f…` artifacts unchanged. Record fresh Cloudflare preparation and tests under a new audit directory with the actual documentation revision and source fingerprint. `npm run build:cloudflare` runs hygiene, Astro/type, unit/content, static build/output and Free asset-limit checks, without browser tests or upload. Custom-origin promotion uses explicit production `DOCS_SITE=https://security.devsatym.xyz` at `/`; non-main native previews use validated `CF_PAGES_URL` and indexing controls. Local checks remain separate from actual project creation, native builds, DNS, certificate issuance and hosted verification.

`npm run validate` retains separate custom/GitHub/legacy compatibility builds/browser suites and restores custom-root output. Read-only `docs-validate.yml` remains the GitHub check for relevant PR/main changes. Edit locally with `npm run dev`, push a work branch for a native preview, review it and passing GitHub checks, then merge/push `main` for an automatic production build. The existing published version stays live while the next build runs. Local saves alone do not publish. Preview and production builds consume Cloudflare Free's500-build monthly allowance; private GitHub Actions has a separate minute/artifact budget. Native Pages does not automatically wait for GitHub CI. The unused manual `docs-pages.yml` is historical. [Cloudflare limits](https://developers.cloudflare.com/pages/platform/limits/), [Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)

## Author, projects and editorial assets

Owner-supplied identity lives in `src/data/author.ts`; optional fields remain hidden until approved. Recheck destination availability before changing `authorLinkAvailability` or a project to live. `src/data/projects.ts` preserves planned/live documentation URLs separately from repository links. Source citations and original upstream ownership remain pinned and attributed. Regenerate the editorial PNG using `node scripts/create-social-image.mjs` after approved identity changes, visually review it, and preserve the static PNG/social URL. Do not optimize/replace original evidence or add unreviewed files to the publication allowlist. Actual remote DNS/TLS/image delivery must be recorded separately from localhost tests.

The complete screenshot inventory lives in `src/data/screenshots.json`. All fourteen displayed originals remain byte-identical to the pinned source, including disclosed terminal/account metadata. The owner's Cloudflare instruction authorizes publishing these existing approved assets. No optional pixel-edit preference was selected, so do not silently replace originals with proposed masks. Any later derivative requires explicit owner direction and a truthful display hash, dimensions, note and bounded mask metadata, while retaining the original source hash. Keep collection dates separate from per-capture revisions and direct evidence separate from contextual relations. Validate all fourteen PNG response bodies and dimensions in fresh profile and hosted checks. Internal privacy plans and record `14-CLOUDFLARE-DEPLOYMENT.md` are not automatically added to the ten-report public allowlist.

Generated private audits, history, captures and test reports are excluded from both Pages build watches and GitHub validation path filters. Authored website inputs, approved public assets, curated report sources and documentation workflows still trigger checks. Store post-deployment receipts in the excluded private audit directory so recording a successful publication does not publish another unchanged artifact.