Skip to content

Say what the build is, not what happened to it - #172

Merged
davidmckayv merged 1 commit into
mainfrom
docs/state-what-is-not-what-happened
Aug 22, 2026
Merged

Say what the build is, not what happened to it#172
davidmckayv merged 1 commit into
mainfrom
docs/state-what-is-not-what-happened

Conversation

@davidmckayv

Copy link
Copy Markdown
Contributor

The README's connector line was a diary entry:

Atlassian, Box, Slack, Salesforce and ServiceNow were reviewed and taken back out: a screen offering five untried connectors claims more than this deployment can stand behind, and re-adding one is a review of that vendor rather than a revert.

Somebody reading a build doc to find out what this deployment can reach does not need the history of what it used to offer. "Rather than a revert" only parses if you were there for the removal. It now says what the catalogue is, and what a Bot is told about it:

Google Drive ships in the catalogue, reached as the person asking. The catalogue carries only vendors this deployment stands behind, so adding one is a review of that vendor. Custom servers must pass URL checks, and any tool not positively classified as a read is treated as a write. A Bot is told which connectors exist here and which it holds, so it says it has not been granted one rather than browsing to the vendor's website.

Two more in the docs

architecture.md described the upstream Better Auth scoping in the past tense — "two administrators saw two different deployments… would have deleted the company's sign-in" — as though it had been fixed upstream. It has not. That is what the plugin still does, and it is the reason OpenBot's own routes exist. Present tense is plainer and more accurate.

architecture.md also described the world before sign-in audit rows existed. Rewritten as what the rows are for.

deployment.md said the app "no longer depends" on secure-context APIs. It does not depend on them; when it stopped is nobody's business.

Left alone

docs/development.md keeps "a file that no longer matches what the generator produced" — that is the consequence of hand-editing a migration, not a note about the past.

Swept the rest of the README and docs for the same pattern; the remaining past tense is all describing audit trail contents ("what was permitted, what was refused"), which is correct.

The README's connector line narrated a decision: five vendors "were
reviewed and taken back out", and re-adding one "is a review of that
vendor rather than a revert". Somebody reading a build doc to find out
what this deployment can reach does not need the history of what it used
to offer, and a sentence that only makes sense if you were there is worse
than no sentence. It now says what the catalogue is and what a Bot is
told about it.

Two in the docs, the same fault:

The identity-provider note explained the upstream plugin's scoping in the
past tense, as though it had been fixed. It has not; that is what the
plugin still does, which is the reason the routes exist. Present tense is
both plainer and more accurate.

The sign-in audit note described a world before those rows existed.
Rewritten as what the rows are for.

`docs/development.md` keeps its "no longer matches", which is the
consequence of hand-editing a migration rather than a note about the
past.
@davidmckayv
davidmckayv merged commit 3fee5d1 into main Aug 22, 2026
8 checks passed
@davidmckayv
davidmckayv deleted the docs/state-what-is-not-what-happened branch August 22, 2026 16:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant