Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

How the Factory's docs and website are built for their public addresses, and who publishes them. Publishing them is the owner's decision of 29 September 2026: both sites, open to indexing, with local paths and archive links stripped and everything else kept. Private session identifiers are stripped too, under the owner's standing rule that private conversation links never go public. It releases no product: Factory stays local infrastructure in development, and all 27 customer-value epics remain open.

Build

npm run publish:build                    # writes docs/ and website/ under <local-cache>
node --test test/public-build.test.ts    # the public build's own tests

node scripts/build-public.ts <outRoot> writes <outRoot>/docs and <outRoot>/website instead. The output is regenerable and never committed. The committed site/ and website/ stay the local builds, byte for byte, and the public build never writes inside the repository.

SiteAddressBuilt from
Docshttps://docs.plumbfactory.fyiThe Markdown in docs/, by the docs site's builder
Websitehttps://plumbfactory.fyiapps/website/, by the website's builder, with every honesty check it runs locally

What changes for publication

  • Local paths become placeholders. Every local machine path and archive location (home directories, other volumes, the evidence archive, the checkout's ignored evidence and state, machine temporary paths) is shown as a placeholder in angle brackets, such as <local evidence archive>, always in code formatting, so sentences and code blocks keep their shape. The footer and the reference note say so.
  • Records are published. Each JSON file in docs/, receipts included, becomes a record page with the same placeholders; every hash, date and count is as committed. A local path that is a key keeps its file's name, as in <local evidence file: portfolio-final.png>, so no two keys of one object become one and each hash still says which file it describes; a key that would still repeat another is numbered, as in <local evidence archive> (2). An image in docs/ that a page links is copied. Any other repository file (source, tests, the README, the handover, the intent) is named without a link, and the website marks such evidence "(not published)".
  • Private session identifiers are removed. In a record, the value of a key naming a session or conversation (session_id, session, thread_id and the like) becomes <private session 1>, <private session 2> and so on, one number for each session in that record, so entries that shared a session still share its number. Any other UUID in a record, such as the one in an image tool's output file name, becomes <private identifier 1> and so on. Each record's note says which of these apply to it.
  • The sites link each other. The website's links into the docs go to the public docs and must resolve there, anchors included; every docs page links back to the website.
  • Indexing is allowed. The website drops its request not to be indexed. Each page names its canonical and Open Graph address, and each site has robots.txt and sitemap.xml.
  • The capture is approved. The dashboard capture's frame says it shows the owner's real Portfolio, approved for publication on 29 September 2026. Its image is still held to the SHA-256 its receipt records.

What stops it

The build writes nothing, and lists every problem, when:

  • any file of either site still holds a local path, a home directory, a private conversation link, a private conversation identifier (a UUID, a UUID written without hyphens as Notion writes a page's, or an identifier after a label such as session_id), an email address or a token-like string. Images are read too. Their text chunks are checked for all of these. Their pixels and signed provenance are checked for paths, links and labelled identifiers, since the provenance carries UUIDs of its own that name the image;
  • a placeholder falls outside code formatting;
  • a link or image resolves neither inside the two sites nor to an outside web address, or names an anchor its page lacks;
  • a page's canonical or Open Graph address is not its own;
  • the docs build warns, or any check of the website fails;
  • either output directory holds anything but an identical previous build. A build never overwrites: remove the old one and build again.
rm -rf <local-cache> && npm run publish:build

Deploy

Only the coordinator deploys, and only with the owner's approval. There is one deploy path: the guarded step in scripts/deploy-sites.ts, from main, through Cloudflare's cf CLI under its factory auth profile. No agent deploys, and nobody deploys with cf by hand.

npm run publish:deploy -- --commit <sha>                 # check, build, rehearse, deploy the docs then the website, verify, record
node scripts/deploy-sites.ts --dry-run --commit <sha>    # every check and cf's own offline dry run; deploys nothing
node scripts/deploy-sites.ts --verify --commit <sha>     # is what is live exactly that commit's build? deploys nothing

<sha> is the full commit main points at. The step builds both sites itself, from a git archive export of that commit, with the export's own builder. The output of npm run publish:build is for reading and review; the step never deploys it.

Each site is a Cloudflare Worker with static assets, not a Pages project. The step deploys prebuilt: it writes each site as cf's Build Output for an assets-only Worker, under <local cache>. That is the committed deploy/<site>/worker.config.json as written, plus the build's files. A cloudflare.config.ts would need cf build and an installed Cloudflare dev-server package, and the Factory installs nothing.

What it may touch

The step reads its targets from deploy/targets.json, a committed file of names and an opaque account reference: the factory profile, the plumbfactory.fyi zone, and each site's Worker and domain. It holds no raw account, zone or Worker ID and no credential. The opaque account reference binds the existing authorised account. Anything more or other in it is refused, and the step names nothing else.

SiteWorkerCustom domainConfig
Docsplumbfactory-docsdocs.plumbfactory.fyideploy/docs/worker.config.json
Websiteplumbfactory-websiteplumbfactory.fyideploy/website/worker.config.json

These are the Workers that served the sites on 29 September 2026, found read-only. The step adopts them and never creates one. It refuses a Worker that is missing, listed twice, serving another domain, or with workers.dev or preview URLs on. It refuses either domain on any other Worker. It also refuses a Worker that the listing shows another Worker, Durable Object, queue or dispatch namespace reaching (a service binding, say), or whose listing does not give those references, because a deploy would then change what that other thing serves.

Each config holds exactly the Worker's name, its one domain and the adopted compatibility date. It serves files as named (htmlHandling: "none") and the build's 404.html for any other address (notFoundHandling: "404-page"). Workers.dev and preview URLs stay off. A route, trigger, binding or any other setting is refused.

Before every cf call the step checks the call against its allow-list:

  • the arguments are one of the six forms below, naming one of the two Workers where a form names one;
  • the environment is exactly the fixed one: nothing inherited, and cf's telemetry and hand-off to a project copy of cf off;
  • the directory is the call's own;
  • for a dry run or a deploy, the staged Build Output is right byte for byte: the committed config, the fixed root config, no account cache, no script, no second Worker, and exactly the build's files.

A call that fails the check never runs.

The cf commands

CommandReaches Cloudflare
cf --versionNo: offline
cf auth whoami --profile factoryReads
cf workers list --per-page 100 --profile factoryReads
cf workers deployments list --worker <Worker> --profile factoryReads
cf deploy --prebuilt --dry-run --worker <Worker>No: offline
cf deploy --prebuilt --worker <Worker> --message "Factory <commit> public build, run <time>" --profile factoryWrites that one Worker

Offline calls run with an empty home, so cf finds no profile or credentials. They also get a dead API address, and sandbox-exec denies them outbound connections. cf auth whoami must show that cf authenticates from the factory profile's own credential file, never a token from the environment, and sees exactly one account. The deploy writes only its Worker: its assets, a new version and its deployment, its workers.dev and preview settings (kept off) and its one custom domain.

cf has no --json flag. Its listings and auth whoami print JSON, which the step reads as untrusted data against the shape it must have. From cf deploy it takes only a version ID, believed only when cf's listing shows that version serving all traffic under this run's message. A refusal never quotes a name, domain or credential source that cf printed.

Reviews

A deploy and a rehearsal need an independent Astra extra-high review and a Codex coordinator acceptance of the exact commit. The owner's 2 October 2026 takeover instruction replaces the retired Fable gate with Codex's final decision. The coordinator records them in <local evidence archive>, which is private and never committed:

{
  "kind": "factory-public-sites-review",
  "commit": "<sha>",
  "reviews": [
    { "reviewer": "astra", "report": "<absolute path of the report>", "sha256": "<the report's SHA-256>" },
    { "reviewer": "codex", "report": "<absolute path of the report>", "sha256": "<the report's SHA-256>" }
  ]
}

Each report's first line must be exactly VERDICT: PASS, and the report must name the full commit. The step refuses a missing reviewer, a report whose SHA-256 differs from the record, a failing verdict and a review of another commit. --verify, which changes nothing, needs no reviews.

Order, and what stops it

  1. Local checks, before any cf call. No Cloudflare, cf or Wrangler variable is set, since cf would use one in place of the profile. main is checked out, clean, at the named commit. For a deploy or a rehearsal, both reviews pass.
  2. The commit's export. The step exports the commit read-only with git archive. Its scripts/deploy-sites.ts and deploy/targets.json must be the running ones, byte for byte, and its Worker configs as above. Its own builder builds both sites into the run's directory; those bytes are staged, deployed and verified.
  3. The tests, except for --verify. The public build's, its host model's and this step's tests run in the export, in an environment of their own, so nothing inherited, such as NODE_OPTIONS, can leave a test out. Every test must run and pass. After the tests the checkout must still be main at that commit, clean.
  4. cf's version is the one the step was checked against (1.0.0-beta.5), and cf authenticates from the factory profile's own credential file with exactly one account.
  5. Adoption, read-only: both Workers as above, each serving one version to all traffic. A gradual deployment is never overridden. Workers routes are not checked: see "Not established".
  6. Both sites staged, then cf's own dry run of each, offline.
  7. The docs first, so that the website's new links resolve when it lands. The step checks the checkout again and reads adoption again (both Workers' domains and references, and the Worker's latest deployment, which must still be the one recorded in step 5), because a deploy replaces the Worker's custom-domain list with the config's and so would remove a domain, or override a deployment, that appeared since. Any change it sees refuses that deploy. Then it deploys and confirms the deploy through cf's listing. When the listing does not show it yet, the step reads it once more after a pause: a read, never a retry. Then it verifies the site over HTTPS, and does the same for the website.
  8. Adoption again, then the record and the receipt.

A deploy whose outcome cannot be confirmed stops the run, and nothing is retried. When cf's listing, read twice, still shows the deployment from before the run, the site is not deployed according to the listing. The record then keeps the version cf printed, if any, since it may exist without a deployment. A deploy lock stops a second deploy while one runs.

What the HTTPS check covers

For each site, against the build that was deployed:

  • every file of the build answers 200 with exactly its bytes, except _redirects and _headers, which are routing configuration and answer 404 with the 404 page;
  • every address that sitemap.xml, a canonical link or an og:url names, the root included, is on the site and answers 200 with the bytes of the file it resolves to; directory addresses resolve only through _redirects;
  • every page names exactly its own canonical and og:url address, and 404.html names none;
  • a missing page and a missing directory answer 404 with the build's 404.html;
  • every answer above gives X-Content-Type-Options: nosniff and Referrer-Policy: strict-origin-when-cross-origin, as the build's _headers sets;
  • the home page links to the other site, and that page answers 200.

The step also asks for each site's root over plain HTTP. A redirect to HTTPS is a zone setting the step neither reads nor changes, and one answer for the root says nothing of every address. So the record reports it as unknown, or absent when the root does not redirect, and never as passed.

Exit status: 0 when every site is deployed, confirmed and verified, or rehearsed, or verified live. It is 1 when the step refused before any deploy, or --verify found a difference. It is 2 when a deploy ran and something after it did not complete; then read the record before doing anything else.

What it records

Each run writes <local evidence archive>. record.json gives the commit, cf's version, the names of the profile's scopes, the reviews it accepted, and the HTTPS checks. For each site it gives the Worker, domain, build digest, the version it replaced, and the new version and deployment. Beside it are a journal written as the run goes, the build's and tests' output, and each cf call's output, bounded. cf's JSON names account email addresses, so the logs keep only its size.

receipt.json is the run's private receipt, written last. It binds the commit, the step files and Worker configs, both review reports and their record, each site's build manifest, and every other file the run kept to their SHA-256. It says what the run did not establish. It stays under the archive: never committed, never published.

Every token-like string and email address in anything the step writes or prints is replaced where it stands, and the rest is kept whole.

Not established

  • That plain HTTP redirects to HTTPS at every address.
  • That no Workers route elsewhere in the account sends requests to either Worker. cf 1.0.0-beta.5 and beta.10 cannot list Workers routes, and the step reaches Cloudflare only through cf, so it does not check routes at all. A route in any zone that points at plumbfactory-website or plumbfactory-docs would serve the new content, and the step would not see it. The step used to refuse without the owner's own reading of the routes, at most fifteen minutes old, which would have made every deploy a manual one. On 2 October 2026 the owner decided against that, saying "let's remove the route check requirement if that's gunna require manual deploys", and accepted this residual. The step never adds, changes or removes a route: its configs hold none.
  • That no Workers route in plumbfactory.fyi sends any of the sites' addresses to another Worker. Such a route runs ahead of a Worker's custom domain, so its Worker, not the deployed one, answers the addresses it matches. The step used to refuse any route in that zone; it no longer reads routes, so it does not see one, and the HTTPS check would see one only at an address it checks. This is part of the residual the owner accepted on 2 October 2026.
  • The fewest OAuth scopes a deploy needs.
  • A live run of this step. It was built and tested with a fake cf. Its first revision ran only read-only listings and offline dry runs with the real cf, and its HTTPS check against the live sites.
  • The Factory's own Cloudflare account. When the sites move there, the Workers, domains and profile are adopted again, and deploy/targets.json changes with them.

Addresses, redirects and the 404 page

Canonical addresses and the sitemap name each page by its file (/execution.html), or a directory index by its directory (/reference/). With htmlHandling: "none", the build's _redirects maps each directory address to its index, beside / /index.html 200. _headers applies X-Content-Type-Options: nosniff and Referrer-Policy: strict-origin-when-cross-origin to every address.

Each site's 404.html asks not to be indexed and has no canonical or Open Graph address. The committed Worker configs set notFoundHandling: "404-page", and the HTTPS check above verifies it after each deploy.

Before this step existed, the coordinator deployed both sites by hand, last from commit 8bedc04 on 30 September 2026. From now on, every deploy goes through this step; none has run through it yet.

Account binding: deploy/targets.json records a domain-separated opaque account reference. The profile must report exactly one canonical account matching that reference. Every account-scoped listing and deploy receives only that validated account ID in its freshly constructed environment; subsequent profile selection cannot redirect the call. Offline checks remain account-free, and staged root configs may not override the account. Raw IDs are withheld from logs and receipts.

Source: docs/how-to/publish-the-sites.md