Repository navigation
docs(deploy): the deployment plan, and the two decisions that unblock it - #18
Merged
Merged
Conversation
Deploy.md is the authority for taking this online. It records the three decisions taken (real models via hosted APIs, a login gate between landing and workbench, Railway), the platform constraints that were verified rather than assumed, the invariants this workstream may not break, five PRs with binding acceptance criteria, and a findings register. Two things about the register are deliberate. Every row carries a file:line so it can be checked instead of believed, and each row is marked `direct` (confirmed in-session by reading the file or resolving the compose config) or `audit` (reported with a citation by a code-audit pass, not independently re-checked). Treating those two as the same kind of claim is how a plan acquires facts nobody verified. The register is not a second backlog. Final_Report.md keeps the single outstanding-work list for the product; Deploy.md covers only what blocks deployment, and where an item is both it gets struck from Outstanding Work in the PR that fixes it. The constraint that outranks the rest is model parity: every figure the UI and the docs display is generated from results/eval-h1-repeat3-2026-07-31/ and is a claim about that exact configuration. All three of its models are available as hosted APIs, so the deployment can match it without substituting anything — and if a future change substitutes one, it says so on the landing page and /methodology or it reverts. CLAUDE.md gets a pointer, not a copy: §2 carries only the seven invariants that stay true whichever PR is in flight, and says explicitly that the backlog lives in Deploy.md. Three copies of "what's left" is the drift pattern this project keeps having to fix. Sections renumbered 2-6 -> 3-7; the two internal §1 references still resolve.
D-5: explicit per-provider client classes rather than a generic OpenAI-compatible adapter. Neither Jina's embeddings response nor SiliconFlow's rerank response is OpenAI-shaped in the part that matters — both carry per-item indices that have to be mapped back to input order — so a shared abstraction would have to model the difference anyway. The cost is recorded: a fourth provider later means writing a class, not setting a variable. D-6: one shared account read from the environment. No user table, no migration. The consequences are written down rather than discovered later: the daily query cap becomes per session rather than per person, and a shared password cannot be revoked for one holder, only rotated. That is adequate for a gated demo and is not an authorization model. Open questions drop from five to two. Team ownership stays unresolved and is the reason this branch is being pushed; the durable fix for the Railway shared-volume constraint stays deferred and recorded.
This was referenced Aug 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
Deploy.md— the authority for taking Dcode online — and pointsCLAUDE.mdat it. Docs only; no runtime code changes.Why a separate document
Deployment turned out to touch three things at once: platform constraints that change the architecture, a handful of real product defects, and two decisions with methodological consequences. Scattering that across commit messages would have lost the reasoning, and putting it in
Final_Report.mdwould have created a second backlog next to Outstanding Work.Deploy.mdcovers only what is unfinished in getting it deployed. Where an item is also a product defect — most are — it gets struck from Outstanding Work in the PR that fixes it, not tracked in two places.What is decided
Deploymerges back tomainin slicesThe constraint that outranks the rest is model parity. Every figure the UI and the docs display is generated from
results/eval-h1-repeat3-2026-07-31/and is a claim about that exact configuration. All three of its models — Jina v2-base-code at 768 dimensions, BGE reranker v2-m3, gpt-4o-mini — are available as hosted APIs, so D-1 can be satisfied without substituting anything. If a future change does substitute one, it says so on the landing page and/methodologyor it reverts. §2 also records what parity of model identity does not buy: identical weights through a provider's API are not bit-identical to local serving, so a future H1 re-run through the APIs is a new run directory, not a refresh of the recorded snapshot.Two Railway constraints that change the architecture
Both verified against Railway's documentation on 2026-08-02 rather than assumed:
repo_workdirsis written by the worker and read by the agent'sread_file/grep/list_directorytools, so those two must share one Railway service. This is a platform workaround, recorded as such, with the durable fix (stop reading source from a shared filesystem) deferred and written down.Findings register
§7 lists 18 findings, each with a
file:line. Every row is markeddirect(confirmed in-session by reading the file or resolving the compose config) oraudit(reported with a citation by a code-audit pass, not independently re-checked). Treating those as the same kind of claim is how a plan acquires facts nobody verified. §7 also records three things that are already correct, so nobody "fixes" them.CLAUDE.md
Gets a pointer, not a copy: §2 carries only the seven invariants that stay true whichever PR is in flight, and says explicitly that the backlog lives in
Deploy.md. Sections renumbered 2–6 → 3–7; the two internal §1 references still resolve.Verification
make checkgreen. Docs-only change; nothing was deployed and no live model API has been called from this codebase.Tag
v1.0-submission(a4612b8) freezes the pre-deployment state.