- MDX 83.6%
- JavaScript 7.3%
- Python 4.5%
- TypeScript 2.1%
- Astro 1.3%
- Other 1.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
dev
9cc78c91e1
All checks were successful
Deploy documentation / deploy (push) Successful in 18m19s
Rewrites stale page descriptions and the glossary against the pinned source, limits the first-steps guide to available actions, adds Start Playing and Clients & Tools pages, fixes relative links that resolved incorrectly in the browser, validates the agent docs index and archive against a published schema, replaces docs-sync with a portable check-only script, removes the retired container deployment files and adds the MIT license. |
||
| .forgejo/workflows | ||
| .vscode | ||
| automation | ||
| public | ||
| scripts | ||
| src | ||
| .gitignore | ||
| .ignore | ||
| .npmrc | ||
| .nvmrc | ||
| AGENTS.md | ||
| astro.config.mjs | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| sidebar.config.mjs | ||
| tsconfig.json | ||
| wrangler.docs-failover.toml | ||
Dysnomia Documentation
Static Astro and Starlight documentation for the Dysnomia contracts, served at https://dys.gui.icu/docs.
Build
Use Node 22.22.2 or later in the Node 22 line, npm 12.2.0, and the committed lockfile:
npm ci --ignore-scripts
npm run build
npm test
The build generates machine-readable indexes at /agent-docs/v1/index.json and /agent-docs/v1/archive.json, normalized Markdown pages at /agent-docs/v1/pages/<id>.md, and /llms.txt. They are derived from src/content/docs, checked against the constraints in scripts/agent-docs.schema.json (published as /agent-docs/v1/schema.json), and are not edited directly. The build fails on an empty or truncated page description.
Cloudflare deployment
npm run build:cloudflare
npx [email protected] pages deploy cloudflare-dist --project-name "$CLOUDFLARE_PAGES_PROJECT" --branch main
npx [email protected] deploy --config wrangler.docs-failover.toml
Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN in the deployment environment. The token needs Pages deployment, Worker script, and Worker route permissions for the configured account and zone.
Pages serves the build at its root and under /docs/. The routing Worker serves dys.gui.icu/docs/ from Pages; other paths remain with the application's origin. DOCS_PAGES_ORIGIN selects the Pages origin.
Remote Git pushes to main run the deployment workflow. Configure the Cloudflare credentials and DOCS_DEPENDENCY_TOKEN as CI secrets, and CLOUDFLARE_PAGES_PROJECT, DOCS_PAGES_ORIGIN, and DOCS_PUBLIC_URL as CI variables. CI verifies all three entry points against the generated documentation revision.
npm run package:cloudflare produces a dashboard-upload ZIP beside the repository, subject to its file-count and size limits. CLI deployment uses cloudflare-dist directly.
Contract references
Use a clean local checkout of the original source repository:
python3 -m venv .venv
.venv/bin/pip install -r scripts/doc_regen_pipeline/requirements.txt
.venv/bin/python scripts/doc_regen_pipeline/prepare_source.py --source-root "$SOURCE_ROOT"
.venv/bin/python scripts/doc_regen_pipeline/port_regenerate.py --source-root "$SOURCE_ROOT" --out /tmp/docs-regenerated
.venv/bin/python scripts/doc_regen_pipeline/adopt_regen.py --scratch /tmp/docs-regenerated
.venv/bin/python scripts/doc_regen_pipeline/verify_provenance.py --source-root "$SOURCE_ROOT"
Review regenerated explanations against source changes before publishing. Unchanged Solidity bytes retain their fingerprint and verification/source dates. Deleted-contract pages remain at their original paths and are listed under Archived Contracts.
Upstream check
npm run sync:docs
automation/docs-sync.mjs compares git ls-remote HEAD of the upstream repository with the revision pinned in scripts/doc_regen_pipeline/mapping.json and records the result. It edits no files, commits nothing and makes no model calls. Regeneration stays a manual, reviewed step.
| Setting | Meaning |
|---|---|
DOCS_UPSTREAM_URL |
Upstream Git URL; defaults to https://github.com/busytoby/atropa_pulsechain.git |
DOCS_SYNC_STATE_DIR |
State directory; defaults to $XDG_STATE_HOME or ~/.local/state on Linux, ~/Library/Application Support on macOS and %LOCALAPPDATA% on Windows, plus dys-astro-docs-sync |
The command writes state.json there atomically with version, checkedAt, upstreamHead, pinnedRevision, updateNeeded and error, and prints one JSON line. When updateNeeded is true the pinned source is behind the upstream. An unreachable upstream records the error, keeps the previous upstreamHead and updateNeeded and exits non-zero. It never reports that no update is needed. A run that finds a fresh lock file skips with exit code 0; a lock older than 15 minutes is replaced.
Example schedules (every three hours):
0 */3 * * * cd /path/to/dys-astro-docs && node automation/docs-sync.mjs >> "$HOME/dys-docs-sync.log" 2>&1
<!-- ~/Library/LaunchAgents/dys-docs-sync.plist (macOS) -->
<plist version="1.0"><dict>
<key>Label</key><string>dys-docs-sync</string>
<key>ProgramArguments</key><array><string>/usr/local/bin/node</string><string>automation/docs-sync.mjs</string></array>
<key>WorkingDirectory</key><string>/path/to/dys-astro-docs</string>
<key>StartInterval</key><integer>10800</integer>
<key>StandardOutPath</key><string>/tmp/dys-docs-sync.log</string>
</dict></plist>
schtasks /Create /TN "Dysnomia docs sync" /SC HOURLY /MO 3 /TR "cmd /c cd /d C:\path\to\dys-astro-docs && node automation\docs-sync.mjs >> %LOCALAPPDATA%\dys-docs-sync.log 2>&1"
License
MIT — see LICENSE.