Docs: Position Currencyinfo as a universal open-source rates service

[massivedev0]

Description

Positions Currencyinfo as a universal open-source rates service rather than an ADAMANT-internal component, and builds the distribution surfaces that positioning needs. ADAMANT stays visible as a production adopter and as the maintainer.

No runtime code is touched. src/ is unchanged, and the only new executable is a dependency-free Markdown link checker.

Product positioning

• README.md rewritten: universal self-hosted rates service first, ADAMANT as adopter and maintainer, prominent links to the landing page, documentation, releases and container package. All Wiki links removed
• package.json: new description, homepage moved to https://currencyinfo.dev, keywords aligned with the repository topics, docs:* scripts. Stays private, since the distributable artifact is the container image
• AGENTS.md: mission and positioning rewritten, new Documentation Policy with a table of what must be updated together, Product Surfaces section, documentation commands added to the validation baseline
• CONTRIBUTING.md: current connector list, a Documentation section, and an "Adding a rate source" checklist
• LICENSE: canonical GNU GPL v3 text added, so GitHub detects the license

Documentation site

A VitePress site in docs/, published to https://currencyinfo.docs.adamant.im. Twenty pages covering overview and positioning, architecture, Docker-first quick start, installation, upgrade and rollback, rate calculation, history and storage, notifications, operations, security, troubleshooting, the REST API, a complete configuration reference synchronized with config.default.jsonc and src/global/config/schema.ts, and one page per connector.

Local search, responsive navigation, edit-on-GitHub links, canonical metadata, a sitemap, and no analytics or third-party telemetry.

CI/CD

• docs-check.yml builds the site on pull requests and holds only contents: read, so it cannot deploy
• docs-deploy.yml deploys to GitHub Pages from master and from published releases, verifies the release tag is an ancestor of master, grants pages: write and id-token: write only to the deploy job, and reports the github-pages environment URL
• publish-docker.yml publishes ghcr.io/adamant-im/currencyinfo on release only, for linux/amd64 and linux/arm64, with semantic plus major and minor tags, OCI labels, build cache, provenance and an SBOM. latest moves only for the newest non-prerelease
• docker-ci.yml builds the image on pull requests and smoke-tests it without pushing: it asserts the OCI labels, asserts no config.jsonc is baked into a layer, starts MongoDB and the service from the shipped config.default.jsonc, confirms non-root execution, and retrieves a rate. No provider credentials are used

Container packaging

• Dockerfile: OCI source, revision, version, description, license and documentation labels; the builder stage is pinned to $BUILDPLATFORM because the compiled output is architecture independent; still non-root with no configuration baked in
• docker-compose.prod.yaml: pulls the published image by default, keeps a commented local-build override for contributors, and pins MongoDB to a supported major version
• docker-compose.yaml: MongoDB pinned to 8.0 instead of latest

Wiki migration

All seven Wiki pages were inventoried, migrated, and corrected. .github/wiki/ holds the replacement tombstones and the publishing procedure. The tombstones are already live: every original slug still resolves and points at its canonical destination.

Corrections made during migration, all of which were wrong on the Wiki:

• groupPercentage was documented backwards. It is the minimum relative distance between the weights of the two heaviest groups, not the share of sources a group must contain
• the API examples used port 36668 instead of 36661, and rateLiftime instead of rateLifetime
• installation required Node.js v20; the service requires v22 or newer
• Saved rates format claimed USD is the only default base coin, while the template configures seven
• the notification examples were secret-shaped, including a realistic twelve-word passphrase

Data source banner

.github/banner-{light,dark}.png regenerated for the current connector set: the five keyless defaults on the top row, the key-gated ones plus the deprecated CryptoCompare below. Currency API ships no logo, so its mark is drawn from the banknotes-on-a-line photo in that project's own README.

Related issue

Refs #50 — deliberately not a closing keyword.

#50 requires the documentation site and the container package to be live and verified, and neither is yet: the Pages deployment needs docs-deploy.yml on master, and the first image needs a release. Merging this should not auto-close the issue; close it by hand once https://currencyinfo.docs.adamant.im serves over HTTPS and ghcr.io/adamant-im/currencyinfo is publicly pullable.

Builds on #49, whose connector set, configuration schema and defaults are the source of truth for everything documented here.

Partially addresses the documentation toolchain half of #54, see the VitePress note below.

Breaking changes

None for the service. src/ is unchanged, and the REST API, configuration schema, rate calculation and stored document layout are untouched. The only change to config.default.jsonc is a comment that pointed at the Wiki and now points at the documentation site.

Two changes affect deployments that use the shipped Compose files:

• docker-compose.prod.yaml now pulls ghcr.io/adamant-im/currencyinfo:latest instead of building from the checkout. Contributors who want a local build uncomment the build block that ships with it
• MongoDB is pinned to 8.0 in both Compose files instead of tracking latest. An existing mongo_data volume created by a newer MongoDB will not start under an older server

How to test

pnpm install --ignore-scripts --frozen-lockfile
pnpm run deps:setup

pnpm test
pnpm run lint
pnpm run format:check
pnpm run build

pnpm run docs:build
pnpm run docs:links

docs:build fails on a dead link inside the site. docs:links checks relative links and heading anchors across every Markdown file in the repository, and resolves links to the published documentation URL against the local docs/ tree, so a broken README.md link fails here rather than after deployment.

Results on 601d31c:

Command	Result
pnpm install --ignore-scripts --frozen-lockfile	Lockfile up to date
pnpm test	28 suites, 266 tests passed
pnpm run lint	Clean
pnpm run format:check	All matched files use Prettier code style
pnpm run build	TSC found 0 issues, 67 files compiled
pnpm run docs:build	Built, no dead internal links
pnpm run docs:links	40 Markdown files checked, all links and anchors resolve
git diff --check	Clean

The container build and smoke test were not run locally, because no Docker daemon was available in the environment the branch was prepared in. docker-ci.yml runs them on this pull request.

To read the site locally:

pnpm run docs:dev

To exercise the container path the same way docker-ci.yml does:

docker build -t currencyinfo:local .
docker network create currencyinfo-ci
docker run -d --name mongodb --network currencyinfo-ci mongo:8.0 --quiet
cp config.default.jsonc config.jsonc
docker run -d --name currencyinfo --network currencyinfo-ci -p 36661:36661 \
  -v "$PWD/config.jsonc:/usr/src/currencyinfo/config.jsonc:ro" currencyinfo:local

curl -s http://localhost:36661/status
curl -s "http://localhost:36661/get?coin=BTC"
docker exec currencyinfo id -u   # must not be 0

Notes for reviewers

Already done outside this diff

• Repository metadata: About description, website https://currencyinfo.dev, and fifteen topics are set
• GitHub Pages: enabled with the GitHub Actions source, custom domain currencyinfo.docs.adamant.im, Let's Encrypt certificate issued, Enforce HTTPS on. The site 404s until docs-deploy.yml reaches master, because the workflow only exists on this branch
• Wiki: tombstones pushed, all seven slugs verified to return 200. The Wiki is deliberately left enabled so inbound deep links keep resolving

Still to do after merge

The container package does not exist yet: publish-docker.yml fires on a published release, so the first image needs a v4.2.0 release from master. Until then, the links to ghcr.io/adamant-im/currencyinfo in README.md and the documentation resolve to a 404, and the package must be made public and connected to the repository once it is first published.

Issue #50 stays open until both public surfaces are live and verified.

Worth a second opinion

• License identifier. package.json still declares GPL-3.0, which SPDX deprecated in favour of GPL-3.0-only and GPL-3.0-or-later. Choosing between them is a licensing decision, so the string was left as it was, consistently across package.json, the container label and the documentation footer
• The CryptoCompare mark in the banner could not be verified: cryptocompare.com no longer serves brand assets and the product is being folded into CoinDesk Data. The mark the repository already used in that slot was kept
• ExchangeRate-API's icon is upscaled from a 48px favicon, the largest asset they publish. It is the softest mark on the banner
• Slack webhook examples in the documentation deliberately do not look like real webhooks. An example with a genuine 24-character token shape trips GitHub push protection in every repository that copies it
• VitePress is on 2.0.0-alpha.20, taken to clear three Vite and esbuild advisories that have no patched 5.x line. Adamant-im/adamant-console already ships a 2.x alpha, so this follows existing practice, but it is an alpha on the canonical documentation site and worth an explicit opinion

Checklist

• English-only repository output
• Markdown formatting follows .markdownlint.jsonc and the writing style in AGENTS.md
• No secrets, webhooks, or passphrases committed or logged; every example credential is unmistakably synthetic
• Documentation updated in the same PR, per the Documentation Policy
• Configuration reference matches config.default.jsonc and src/global/config/schema.ts
• No link to the deprecated GitHub Wiki was added
• pnpm test, pnpm run lint, pnpm run format:check and pnpm run build pass
• pnpm run docs:build and pnpm run docs:links pass
• git diff --check passes
• Targets develop and references the issue with a closing keyword
• No unit tests added: this change touches no runtime code. The new scripts/check-docs-links.mjs is exercised by docs-check.yml on every documentation pull request

🤖 Generated with Claude Code

[dev-adamant-im]

What works well

• The PR consistently positions Currencyinfo as a universal self-hosted product while keeping ADAMANT visible as a production adopter and maintainer
• The documentation is broad, navigable, and closely aligned with the provider behavior delivered by #49
• The new workflows use narrow permissions, keep pull-request jobs read-only, and gate release publication on membership in master
• The container remains non-root, excludes config.jsonc, and starts successfully from the shipped defaults against a clean MongoDB database
• No runtime source files or production dependency versions are changed

Needs attention

Six inline findings need changes before merge: one release-tagging issue and five documentation, workflow, or dependency issues. The most consequential problem is that docker/metadata-action can still generate latest implicitly, bypassing the explicit newest-release decision.

The PR also contains Closes #50, while the documentation URL and GHCR package currently return 404. Issue #50 explicitly requires both public surfaces and their live verification, so it should remain open until the Pages deployment and first release-driven container publication have completed and the package is public.

Dependency modernization and the documentation toolchain advisories are tracked in #54.

Findings summary

• [P1] Disable metadata-action automatic latest generation so only the guarded raw tag can move it
• [P2] Replace the public Compose port mapping instead of appending a loopback mapping
• [P2] Document the required 4.1.2 configuration migration before claiming in-major compatibility
• [P2] Replace the vulnerable Vite and esbuild versions introduced through VitePress
• [P2] Keep chmod privileged after changing the configuration file owner
• [P2] Run the documentation link workflow when any checked Markdown file or the checker itself changes

Validation performed

• pnpm test --runInBand: 28 suites and 266 tests passed
• ESLint, pnpm run format:check, pnpm run build, pnpm run docs:build, pnpm run docs:links, and git diff --check passed
• The ARM64 production image built locally and ran as UID 1000 without an embedded config.jsonc
• A clean MongoDB 8.0 smoke test reached ready: true, fetched from 5/5 default sources, and returned positive BTC, ETH, and ADM rates
• Local documentation rendering, navigation, and search worked
• Both GitHub pull-request checks passed on the reviewed head

[massivedev0]

All six inline findings are addressed, and the threads are resolved.

Finding	Resolution
[P1] Implicit latest generation	flavor: latest=false set, so the guarded raw entry is the only source of latest
[P2] Compose port override appends	Both examples use !override, with the merge semantics, the v2.24 requirement, the older-Compose fallback and a docker compose config verification step
[P2] Missing 4.1.2 configuration migration	New section in docs/guide/upgrading.md, linked from the intro, the pre-upgrade checklist and both upgrade paths
[P2] Vulnerable Vite and esbuild	vitepress upgraded to 2.0.0-alpha.20, resolving Vite 8.2.2
[P2] Unprivileged chmod after sudo chown	sudo chmod in all five places, plus the reason where the instruction first appears
[P2] Narrow documentation link workflow trigger	Trigger widened to **/*.md and scripts/check-docs-links.mjs

On Closes #50

Agreed, and changed. The pull request body now says Refs #50 rather than Closes #50, and records that the issue stays open until https://currencyinfo.docs.adamant.im serves over HTTPS and ghcr.io/adamant-im/currencyinfo is publicly pullable. Neither can happen before this lands on master and a release is published, so auto-closing on merge would have marked the issue done while two of its required public surfaces still returned 404.

Verification

Command	Result
pnpm install --ignore-scripts --frozen-lockfile	Lockfile up to date
pnpm test	28 suites, 266 tests passed
pnpm run lint	Clean
pnpm run format:check	All matched files use Prettier code style
pnpm run build	TSC found 0 issues, 67 files compiled
pnpm run docs:build	Built on Vite 8.2.2, no dead internal links
pnpm run docs:links	40 Markdown files checked, all links and anchors resolve
pnpm audit	2 advisories, both pre-existing qs findings under @nestjs/platform-express
git diff --check	Clean

Two findings were checked against the code rather than taken at face value, and both reproduced exactly as reported:

• the stock 4.1.2 template fails the 4.2.0 schema with precisely the two api_key errors, before the HTTP port opens. The documented migration steps were then validated in the other direction, confirming that both the minimal path and the full one parse
• the Vite and esbuild advisories have no patched 5.x line, which is why this is an upgrade rather than an override

The container build and smoke test still run in CI rather than locally, since no Docker daemon is available in the environment this branch is prepared in.

[adamantmm]

⚡️