docs: audit and correct all project documentation for external readers - #293
Closed
kauereinbold wants to merge 8 commits into
Closed
docs: audit and correct all project documentation for external readers#293kauereinbold wants to merge 8 commits into
kauereinbold wants to merge 8 commits into
Conversation
Badge URLs pointed at a nested workflows/pull-request/ and workflows/tests/ path that does not exist; the workflow files are flat under .github/workflows/, so every CI badge except two was a broken link. Port list only documented the .NET and Go API instances; the C++ instance on 5002 was missing. The stale kaueereinbold.github.io Pages URL and a postgres/ganache compose command missing its required profile are also corrected.
…mmands The structure tree listed src/server/data/ and a root test/ directory that do not exist, and omitted the Go, C++, and migration-runner services. The migration section implied the API applies migrations directly, contradicting the dedicated MigrationsRunner service. The postgres/ganache compose commands were missing the required --profile flag, so postgres never actually started as written.
Replaced the unmodified Next.js create-app boilerplate (changelog, generic 'Learn More' links, a dev-scratch note about Google Fonts being disabled in a sandbox) with real documentation: prerequisites, NEXT_PUBLIC_API_BASE_URL from .env.example, local dev vs Docker setup, test/build/lint commands from package.json, and the actual component structure under src/app/.
…-voice notes Go README: documented endpoints used a singular /api/reminder/:id path while the service actually routes /api/reminders/:id (plural, verified in cmd/app/main.go); the id example used an integer instead of the service's uuid ids; the container-vs-host port split (8080 in-container, 5001 via Compose) was not called out; removed a leftover assistant-voice offer to generate OpenAPI docs. Cypress README: reworded the CI binary-download notice as plain CI guidance instead of sandbox framing, and corrected the GitHub Pages base URL - it pointed at a kaueereinbold.github.io handle that 404s; the live deployment (verified via cypress.config.js and the Pages workflow) is jumperck.github.io/Reminders. Blockchain README: audited npm scripts against package.json (all five match), contract filenames against blockchain/contracts/, and the scaffolding note - already accurate, no changes needed.
agents.md hardcoded a personal absolute path (/home/kaue/repos/...) in the quick-start snippet and in the Resources section, including a link to a specs repository that is not part of this repository; replaced with a git clone + relative-path flow. copilot-instructions.md described the Go API's internal layout as internal/handlers| repository|models, which does not exist - the real layout (verified in cmd/app/main.go) is cmd/app/ + pkg/api/ + pkg/models/. Both guides undercounted the load-balanced API instances as two (.NET + Go) when Nginx actually balances three (.NET, Go, and C++, verified in infrastructure/nginx.conf). The migration runner's /healthz:8081 and the Go API's /health were two genuinely different endpoints that read as conflicting at a glance; both docs now say so explicitly. Both guides also printed the Ganache test private key inline; replaced with a placeholder pointing at .env.example.
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
1 participant
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.
Summary
Full pass over every markdown file in the repo, checked against the actual
source, config, and live deployments rather than assumed. Grouped into five
commits by area:
workflows/pull-request/and
workflows/tests/path; fixed to the real flat.github/workflows/layout. Documented the C++ API instance (port 5002) alongside the .NET and
Go instances. Fixed a stale GitHub Pages URL and a
docker composecommand missing its required
--profileflag.don't exist, added the Go/C++/migration-runner services), reconciled the
migration section with the actual MigrationsRunner service, and fixed
compose commands missing profiles.
with real setup, environment variable, and test documentation matching
the actual
package.jsonand.env.example.(
/api/reminder/:id) to match the real plural route inmain.go, removeda leftover assistant-voice line, reworded a CI notice, and corrected the
GitHub Pages base URL (verified live: the previously documented handle
404s, the correct one is
jumperck.github.io). Blockchain README's npmscripts were checked against
package.jsonand found accurate as-is.filesystem path, fixed the Go API's internal package layout to match the
real
cmd/app+pkg/api+pkg/modelsstructure, corrected the APIinstance count from two to three (Nginx load-balances .NET, Go, and C++,
verified in
infrastructure/nginx.conf), clarified two distinct healthendpoints that read as conflicting, and replaced an inline test private
key with a pointer to
.env.example.The solidity tutorial, Study chat-mode guide, and both issue templates were
read end-to-end and found accurate - no changes needed there.
Config/secret hardening (docker-compose env-driving, hardhat key handling)
is intentionally out of scope here - this PR only touches documentation.
That's tracked separately.
Test plan
actual source,
package.json, or compose file it describesCloses #221