The setup path does not exist: the onboarding guide's technical pointer is an empty link

[Polichinel]

⚠ This issue was rewritten 2026-08-02. The original body contained two false claims, both produced by regex searches whose null results were reported as findings. They are corrected below and the retraction is kept at the bottom rather than deleted.

The problem, verified

The pieces for a clean environment setup all exist and work. What does not exist is a path through them — and the one document that should provide that path contains a dead link exactly where the path belongs.

What is actually true — each item read, not grepped

.env files on disk — 6, in 3 repos. All three containing real secrets are gitignored (verified per-file with git check-ignore):

File	Real secrets	Gitignored
views-models/.env	yes — 16 declared vars	✓
views-faoapi/.env	yes	✓
views-faoapi/.env.bak-20260720	yes — a backup with no stated purpose	✓
three .env.example files	no	tracked

Who reads what at runtime:

Repo	Reads	Resolves to
views-pipeline-core	model_path.py:371 → model_path.root / ".env"	views-models/.env
views-faoapi	managers/api.py:139 → APIPathManager.root / ".env" (its own root, managers/model.py:254)	its own file
views-crafdapi	the same line, inherited by copy	would need its own
views-postprocessing	nothing — asserts the launcher assembled the env (þing-02 P1)	—
views-models	no Python loads dotenv. postprocessors/un_fao/run.sh:23-27 sources .env and exports ONE variable by name	is the source
views-appwrite	nothing, no runtime	—

The good pattern already exists and already runs. views-models/tools/registry_to_env.py reads coordinate_registry.toml and emits the non-secret coordinates; it cannot emit a secret, because the registry holds secrets as slots with no value. views-faoapi/deployment/registry_to_env.py is its twin. un_fao/run.sh:88 already calls it. On that path, coordinates already come from git and only the key comes from .env.

The actual gap

docs/Onboarding Resources/views_platform_onboarding_guide.md is the platform's entry point, and its technical-setup pointer is empty.

• Line 31: [Internal Tech Guide]() — literally empty parentheses
• Line 71: [Internal Tech Guide] — no link at all

The guide mentions no .env, no credentials, no environment variables, and lists 6 repos out of 20+. It is a navigation guide; the place where it would hand off to technical setup is a dead link.

So a newcomer — or the maintainer on a new machine — follows the one documented entry point and arrives at nothing.

Secondary finding

views-faoapi requires 8 variables (_REQUIRED_APPWRITE_ENV_VARS, api.py:41-50). Seven are coordinates the registry already owns, and api.py already contains _registry_coordinates() and _validate_env_against_registry() — it reads the registry and treats it as canonical. Only APPWRITE_DATASTORE_API_KEY is a genuine secret.

So faoapi requires from a hand-written file seven values it already knows how to read from git. This is not a defect in any single file; it is the pattern from un_fao/run.sh not yet applied here.

What this issue does NOT propose

Not "one .env for the whole platform." That is impossible: views-faoapi deploys standalone to Hetzner where views-models does not exist, and deployment/bootstrap.sh exists to bridge exactly that.

The end state is not one file. It is one secret and zero coordinates per machine, which makes the file count stop mattering.

Work

• Fill the [Internal Tech Guide]() dead link — or delete the reference. A pointer to nothing is worse than no pointer: it tells a reader the answer exists and they failed to find it.
• Write the environment/credential setup path, wherever that link lands. It does not exist in any repo today.
• Apply the un_fao/run.sh pattern to faoapi — resolve its seven coordinates from the registry instead of .env, using the reader already in that repo. Reduces its .env to one line.
• Apply the same to views-crafdapi at birth. Free now, a migration later.
• Delete views-faoapi/.env.bak-20260720 — a third file of real secrets with no stated purpose.

Acceptance criteria

• The onboarding guide's technical pointer resolves to a real document.
• That document was followed end-to-end on a machine that had never run the platform — not merely written. Every place it fails is recorded.
• The path requires the operator to supply one secret and zero coordinates.
• views-crafdapi never acquires a second .env habit.

Why here

The registry is homed in this repo and this is seam contract §4. The work lands mostly in views-faoapi and the platform docs repo; this issue holds the shape and the acceptance criteria.

---

Retraction — what the original body got wrong

Kept rather than deleted, because the failure mode matters more than the two facts.

1. "views-faoapi/.env.example is lying — it declares 1 variable and the code requires 8." False. That file deliberately serves two audiences — a caller needs one key; a runner needs the server set — and it points at docs/ADRs/active/013_environment_variable_validation.md, which lists all eight in a table. It also deliberately refuses to put infrastructure values in a template, which is what seam contract §4 requires. The chain works. I produced the claim with a regex matching only ^[A-Z_]+= assignment lines, which cannot see prose comments, then reported it as "the file only tells you about one variable."

2. "No new-machine setup doc exists anywhere." False. docs/Onboarding Resources/views_platform_onboarding_guide.md exists. My find used -maxdepth 3 and never searched for "onboard". Proven broken by pointing it at views-datafactory/docs/guides/credential_setup.md, a file cited earlier in the same session: old query 0 hits, correct query 1.

Both errors are one fault: a null result from a hand-written pattern reported as a fact about the world rather than a fact about the pattern. That is Cluster J — "cannot distinguish 'no' from 'I could not tell', and answers anyway" — the defect class views-pipeline-core#339 was opened to kill, reproduced while writing an issue about tidiness.

The rule adopted as a result: a negative result is not a finding until the query has been shown to find a known positive. Every claim in the corrected body above was re-verified that way, or by reading the file in full.

[Polichinel]

Re-audited in code 2026-08-12 — 2 of 5 items are done, and the blocker is structural rather than unstarted

Item	State, verified in code
Fill the [Internal Tech Guide]() dead link	❌ structurally blocked — see below
Write the environment/credential setup path	❌ the pieces now exist; the document does not
Apply the un_fao/run.sh pattern to faoapi	✅ DONE — deployment/bootstrap.sh builds .env.faoapi with coordinates from the registry, FATAL if the registry is absent
Apply the same to views-crafdapi	✅ DONE — it has both deployment/bootstrap.sh and deployment/registry_to_env.py
Delete views-faoapi/.env.bak-20260720	❌ still on disk — but never tracked (gitignored), so this is a local-machine cleanup, not a repo change

The blocker is not that nobody has got to it

docs/Onboarding Resources/views_platform_onboarding_guide.md is in no repository. It sits untracked in the workspace root, which is not a git checkout. Verified by searching every sibling's development branch: zero hits.

So no pull request in any repo can fill that link. This is not "unstarted work"; the file has no owner. Both dead links are still there — line 31 [Internal Tech Guide]() and line 71 [Internal Tech Guide] with no link at all.

This needs an operator decision: which repository owns platform onboarding? Once answered, the link and the setup path become ordinary work. Until then they cannot be assigned to anyone.

What changed under this issue while it waited

The secondary finding — "faoapi requires 8 variables, seven of which are coordinates the registry already owns" — is now half addressed. api.py:41-50 still requires the same 8 names, but deployment/bootstrap.sh resolves them from the registry and writes the service environment file. That is the correct shape under seam contract §2 and the new §4.2 (appwrite-seam-v1.7.0): the launcher owns and writes, the library borrows and never sources. The app reading them from its environment is not the defect; a second writer would be.

So the pattern this issue asked for has been applied. What remains here is documentation with no home.

Suggested re-scope

Split it. The two applied items are done and this issue should say so rather than reading as five open tasks. What is left is one operator decision (guide ownership) plus the writing that follows it, and one rm on your laptop.

Related: #26 S9 is the same dead link and is blocked on the same missing fact.

[Polichinel]

⚠ Correction — my previous comment was wrong on its central claim

I wrote, an hour ago and twice before that, that the onboarding guide "is in no repository — it sits untracked in the workspace root" and that therefore "no pull request in any repo can fix that link."

That is false. The guide is tracked in views-platform/docs, at Onboarding Resources/views_platform_onboarding_guide.md.

How I got it wrong: my search globbed sibling directories matching views-* and the repository is checked out as docs/. A negative result from a search that could not have found the thing is evidence about the search. This platform has a rule about exactly that — a probe is not evidence until it has been shown to find a known positive (register C-67) — and I did not apply it to my own.

What is actually true, and it is a much smaller problem

The Internal Tech Guide already exists, tracked, in the same folder: Onboarding Resources/internal_technical_guide.md. The last commit on that repository is "Merge pull request #74 from views-platform/internal_tech_guide".

So this issue's first item is a broken relative link to a file sitting next to it. Not structural. Not blocked. One line.

But the real finding is worse than the broken link

I read the target. internal_technical_guide.md mentions Appwrite, the registry, credentials, or .env exactly zero times.

It tells a newcomer that run.sh sets everything up automatically. That was true when written. It is no longer true on the delivery path: views-models/postprocessors/un_fao/run.sh now sources tools/credentials/platform_env.sh, which requires a sibling views-appwrite checkout and is FATAL without one. The guide also routes viewser configuration through "refer to Jim or Mihai".

Filling the link as it stands would point a new contributor at instructions that fail. The dead link at least fails honestly. That reordering matters for this issue: fix the target first, then the link.

Revised state of this issue

Item	State
Fill the [Internal Tech Guide]() link	not blocked — one line in views-platform/docs, but do it after the next row
Write the environment/credential setup path	the executable version already exists — bootstrap.sh in views-models (CI-tested with a fixture registry and a fake secret), plus platform_env.sh. What is missing is the guide pointing at them
Apply the pattern to faoapi	✅ done
Apply it to views-crafdapi	✅ done
Delete views-faoapi/.env.bak-20260720	still on disk, never tracked — a local cleanup

Where this lands

Filed on views-platform/docs (link fix + the stale-setup finding). The agreed split, which the operator confirmed: docs owns "where do I go"; the repos own "what do I run"; nothing executable is described in prose in a repo with no CI. Setup instructions become a pointer to bootstrap.sh, which cannot go stale silently because CI runs it.

Nothing here is blocked on views-appwrite.

[Polichinel]

Closing: nothing here is owed by this repository, and everything that remains is tracked where it can actually be done.

Final state of the five items, each verified at source

Item	Disposition
Apply the un_fao/run.sh pattern to faoapi	✅ DONE — deployment/bootstrap.sh writes .env.faoapi as registry coordinates + one operator secret. Tracked as views-faoapi#349, which appears finished and simply not closed
Apply the same to views-crafdapi	✅ DONE — it has both deployment/bootstrap.sh and deployment/registry_to_env.py
Fill the [Internal Tech Guide]() link	→ views-platform/docs#82
Write the environment/credential setup path	→ views-platform/docs#82 — the executable version already exists (bootstrap.sh, CI-tested with a fixture registry and a fake secret); what is missing is the guide pointing at it
Delete views-faoapi/.env.bak-20260720	→ your laptop. The file was never tracked in git, so no repository can remove it

The ordering constraint, carried to #82

Do not fill the link first. internal_technical_guide.md mentions Appwrite, the registry, credentials or .env zero times, and still tells newcomers run.sh handles setup — which is false on the delivery path, where platform_env.sh is FATAL without a sibling views-appwrite checkout. Filling the link points people at instructions that fail. The dead link fails honestly; that is the better of the two states until the target is fixed.

Two corrections this issue accumulated, kept rather than deleted

1. I claimed three times that the guide was "in no repository". It is in views-platform/docs; my search globbed views-* and missed a checkout named docs. A null result from a probe that could not have found the thing is evidence about the probe — this platform's own rule (C-67), which I applied to gitleaks and not to myself.
2. I then filed views-platform/docsD-05 ruled: reservations live in [planned] #83 duplicating Back-merge main into development #82 — while auditing the checklist that names Back-merge main into development #82. D-05 ruled: reservations live in [planned] #83 is closed; its content moved to Back-merge main into development #82.

Where this is now tracked

• S9 — The onboarding guide's [Internal Tech Guide] link is empty docs#82 — the guide and its link (epic [EPIC] Establish single ownership of the Appwrite environment #26 S9)
• views-appwrite#26 — the epic, 9 of 10 shipped

Nothing further from this seat.