docs: add MkDocs documentation site with Diátaxis structure#91
docs: add MkDocs documentation site with Diátaxis structure#91jmgilman wants to merge 13 commits into
Conversation
Adds a Material for MkDocs documentation site under docs/ with a 17-page Diátaxis information architecture: audience-grouped Developer and Operator guides over generic Reference, Recipes, Troubleshooting, and Concepts sections. Migrates docs/host-access.md into developer/connecting-tools.md. Tooling: mkdocs.yml (Material theme, collapsing left-sidebar nav), Moon tasks root:docs and root:docs-serve (mkdocs run through uv), and a GitHub Pages CI workflow (build --strict on PRs, deploy to Pages on master). Drafted grounded in the code and verified end to end: mkdocs build --strict is clean, CLI flags/defaults match the binary, all recipe manifests byte-match examples/ and pass CRD-schema + dry-run validation, and the documented commands were run against a live yacd devnet. The live run corrected two host-workflow bugs the static drafts missed: yacd topup must be wrapped in yacd run to reach the cluster-internal faucet, and yacd list needs -A to show a network in its own namespace. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kusari Analysis Results:Caution Flagged Issues Detected The dependency analysis found no issues. However, the code analysis identified five high-severity supply-chain risks in the newly introduced GitHub Actions workflow (.github/workflows/docs.yml). All five actions are pinned to mutable version tags rather than immutable commit SHAs, meaning if any tag is silently reassigned to a malicious commit, arbitrary code will execute in the CI runner with no visible indication. The risk is highest for actions/configure-pages and actions/deploy-pages, which run with pages: write and id-token: write permissions — a compromise of either could result in unauthorized GitHub Pages deployments or OIDC token abuse. The third-party action astral-sh/setup-uv adds additional supply-chain exposure beyond GitHub-owned actions. The ws:// references found in documentation files are confirmed false positives and do not affect this recommendation. We strongly recommend addressing the following before merging: (1) Pin actions/checkout@v4 to its immutable commit SHA, (2) Pin astral-sh/setup-uv@v4 to its immutable commit SHA, (3) Pin actions/upload-pages-artifact@v3 to its immutable commit SHA, (4) Pin actions/configure-pages@v5 to its immutable commit SHA — this is critical given the elevated permissions, (5) Pin actions/deploy-pages@v4 to its immutable commit SHA — this is the highest-risk action in the workflow due to write permissions on Pages and OIDC. Tools such as the StepSecurity Harden-Runner or GitHub's own pinning guidance can help identify the correct SHAs for each action. Note View full detailed analysis result for more information on the output and the checks that were run. Required Code Mitigationsactions/checkout is pinned to a mutable version tag (@v4). If this tag is reassigned to a malicious commit, arbitrary code could run in your workflow. Pin this action to a specific immutable commit SHA.
astral-sh/setup-uv is a third-party action pinned only to a mutable tag (@v4). Third-party actions carry additional supply-chain risk compared to GitHub-owned actions. Pin this action to a specific immutable commit SHA.
actions/upload-pages-artifact is pinned to a mutable version tag (@V3). Pin this action to a specific immutable commit SHA.
actions/configure-pages is pinned to a mutable version tag (@v5) and runs in a job with pages: write and id-token: write permissions. A supply-chain compromise here could enable unauthorized deployments or OIDC token abuse. Pin this action to a specific immutable commit SHA.
actions/deploy-pages is pinned to a mutable version tag (@v4) and runs with elevated permissions (pages: write, id-token: write). This is the highest-risk unpinned action in this workflow. We strongly recommend pinning this action to a specific immutable commit SHA before merging.
Found this helpful? Give it a 👍 or 👎 reaction! |
![kusari-inspector[bot]](https://avatars.githubusercontent.com/in/1220830?s=60&v=4){kind=small}
| build: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 |
There was a problem hiding this comment.
actions/checkout is pinned to a mutable version tag (@v4). If this tag is reassigned to a malicious commit, arbitrary code could run in your workflow. Pin this action to a specific immutable commit SHA.
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: astral-sh/setup-uv@v4 |
There was a problem hiding this comment.
astral-sh/setup-uv is a third-party action pinned only to a mutable tag (@v4). Third-party actions carry additional supply-chain risk compared to GitHub-owned actions. Pin this action to a specific immutable commit SHA.
| - uses: astral-sh/setup-uv@v4 | ||
| - name: Build docs | ||
| run: uv run --with mkdocs-material==9.7.6 mkdocs build --strict | ||
| - uses: actions/upload-pages-artifact@v3 |
There was a problem hiding this comment.
actions/upload-pages-artifact is pinned to a mutable version tag (@V3). Pin this action to a specific immutable commit SHA.
| name: github-pages | ||
| url: ${{ steps.deployment.outputs.page_url }} | ||
| steps: | ||
| - uses: actions/configure-pages@v5 |
There was a problem hiding this comment.
actions/configure-pages is pinned to a mutable version tag (@v5) and runs in a job with pages: write and id-token: write permissions. A supply-chain compromise here could enable unauthorized deployments or OIDC token abuse. Pin this action to a specific immutable commit SHA.
| steps: | ||
| - uses: actions/configure-pages@v5 | ||
| - id: deployment | ||
| uses: actions/deploy-pages@v4 |
There was a problem hiding this comment.
actions/deploy-pages is pinned to a mutable version tag (@v4) and runs with elevated permissions (pages: write, id-token: write). This is the highest-risk unpinned action in this workflow. We strongly recommend pinning this action to a specific immutable commit SHA before merging.
State that `yacd devnet` needs Docker running, and that the CLI downloads and caches a pinned, checksum-verified k3d binary on first use (under ~/.local/share/yacd/bin), so the slower first run is not surprising. Applied to the getting-started tutorial, the Home teaser, and the CLI reference. Link k3d and Docker at their first mention on each page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - 6919013 performed at: 2026-06-03T02:19:25Z - link to updated analysis |
Enable Material's automatic color mode: the site follows the operating system's light/dark preference by default, with a header toggle to switch between auto, light (default scheme), and dark (slate scheme). No custom colors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - 3624a22 performed at: 2026-06-03T02:50:36Z - link to updated analysis |
In the getting-started tutorial, the reminder to keep the wallet address and network magic (and that the Try: commands are the next steps) reads better as a Material note admonition than as inline prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - b09dfdd performed at: 2026-06-03T02:51:28Z - link to updated analysis |
# Conflicts: # docs/host-access.md
…-namespaces list) Align the docs branch with PR #93 (merged): `yacd list` now defaults to all namespaces (`-A` removed); `yacd topup NAME LOVELACE` takes a positional lovelace and self-forwards the faucet/Kupo, so the `yacd run` wrapper and `--faucet-url` are no longer needed; and the new `yacd init` prints a commented, ready-to-run environment template. Make `yacd init > yacd.yaml` the default starting point in the "Defining networks" guide (scaffold, edit, `yacd up`), add an `init` reference section and Commands-table entry, and revert the now-stale `list -A` / topup-under-`run` examples added earlier. Verified: mkdocs build --strict clean; `yacd init` -> `yacd up --dry-run` renders a valid CardanoNetwork; init/topup/list `--help` match the docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - bf7fd98 performed at: 2026-06-03T19:27:47Z - link to updated analysis |
Session 058 added `yacd install`, a CLI-native operator install that renders the bundled chart in-memory and SSA-applies it (no Helm/OCI/Docker). Per the co-equal decision, operator/installation.md now presents `yacd install` and `helm install` as tabbed equals across Install / Upgrading / image-verification / Uninstall, with shared Prerequisites and Verify. The CLI reference gains an `install` section + Commands-table row (namespace default yacd-system, --wait/ --timeout/--dry-run/-f/--set/--set-string, operational-values-only + digest-pin nuance, the Plan: dry-run line). Light cross-links from configuration.md, networks.md (the verbs need an installed operator), and the Home routing. Verified: mkdocs build --strict clean; `yacd install --help` matches; live smoke on a fresh k3d cluster — dry-run (install, installed none -> v0.1.1) -> real install (yacd-system created, manager Ready, CRDs registered) -> re-apply dry-run -> `yacd up demo` reconciled to Ready -> clean teardown. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - b6bb381 performed at: 2026-06-04T02:50:58Z - link to updated analysis |
…ion install pin, 0.2.0
Sessions 059 and 061 removed the in-cluster HTTP faucet entirely: `yacd topup`
is gone, `spec.chainAPI.{faucet,wallet}` and the FaucetReady/WalletReady
conditions are deleted, and the YACD_FAUCET_* env vars and endpoints.json
faucetUrl are removed. Funding is now CLI-native: every local network gets a
genesis-funded `faucet` wallet, and `yacd wallet {list,add,topup,export,remove}`
builds, signs, and submits transactions directly over Ogmios/Kupo.
- Rewrote funding.md around `yacd wallet`; updated getting-started step 5,
connecting-tools, testing, troubleshooting, recipes, index, and the
architecture/security concepts to the wallet model (security now covers wallet
key custody + local signing instead of the deleted topup trust gate).
- reference/cli.md: replaced the `topup` section with a `wallet` section, dropped
the faucet rows from the YACD_* contract / endpoints.json / list / info,
retabled the Commands list.
- reference/cardanonetwork.md / environment.md: removed the faucet/wallet spec,
status, conditions, and explicit-field rows.
- Install (#109/#87): operator is now appVersion-tag-pinned (not digest); fixed
the install docs (`image.*` all repoint now), bumped version references to
0.2.0/v0.2.0, and dropped the removed faucet image/flag from configuration.md.
Verified: mkdocs build --strict clean; full residual-reference sweep clean;
`yacd wallet`/`install` --help match. Live smoke pending.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - 5248816 performed at: 2026-06-05T02:32:31Z - link to updated analysis |
Sessions 060 (design + P1) and 062 (P2+P3, release v0.2.1) added directly reachable chain-API access so the CLI can skip the per-command port-forward. - reference/cardanonetwork.md: added `service` (ServiceExposureSpec: type ClusterIP|NodePort, nodePort) + `externalURL` to the ogmios/kupo spec, an "External access" explainer, and `externalURL` on ServiceEndpointStatus. - reference/cli.md: `--ogmios-url`/`--kupo-url` on wallet add/topup; a new "Chain access resolution" section (flag > YACD_*_URL env > probed externalURL > port-forward); run/devnet/YACD_* updated (devnet now exposes Ogmios/Kupo on localhost:1337/1442; the env vars are inputs too). - developer/connecting-tools.md + getting-started.md + concepts/architecture.md: the resolver / host-reachable devnet narrative (also dropped a stale "faucet" from the run-forwards list missed in the faucet-removal pass). - environment.md: noted the optional ogmios/kupo service/externalURL fields. - troubleshooting.md: devnet host-port collision + unreachable-externalURL note. - Version refs bumped 0.2.0 -> 0.2.1. Verified: mkdocs build --strict clean; residual sweep clean; wallet add|topup --help show the new flags. Live smoke pending. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Kusari PR Analysis rerun based on - 9a7291a performed at: 2026-06-06T06:07:23Z - link to updated analysis |
1 participant
Summary
Adds a Material for MkDocs documentation site under
docs/, following a Diátaxis information architecture. Structure and decisions follow the approved proposal (session 052).17 pages, left sidebar with collapsing groups:
examples/manifest, mirrored verbatimYACD_*contract live only in the CLI reference, CRD fields only in the CRD references, manifests only in Recipes.Migrates
docs/host-access.mdintodeveloper/connecting-tools.md.Tooling
mkdocs.yml(Material theme, default collapsing nav)root:docsandroot:docs-serve(mkdocs run throughuv).github/workflows/docs.yml:mkdocs build --stricton PRs touching docs; deploy to GitHub Pages on merge tomasterHow it was built and verified
Drafted by per-page agents grounded in the actual code, then two review passes:
values.yaml/cmd/options.goand the real CLI--help. Fixed in place (removed an inventedkubectlprerequisite, de-duplicated manifests into Recipes, corrected a mis-attributed "admission webhook", fixedconnectwrongly described as settingYACD_*, etc.).mkdocs build --strictis clean (no broken links/nav);helm lint/helm templatepass; every documented CLI flag/default matches the binary; all 8 recipe manifests byte-matchexamples/and pass CRD-schema +--dry-runvalidation.Live smoke: the documented commands were run against a real
yacd devnet.info,exec ... query tip,run(YACD_*injection) all behaved as documented. The live run found and fixed two host-workflow bugs the static drafts missed:yacd topupmust be wrapped inyacd run(with--faucet-url "$YACD_FAUCET_URL") to reach the cluster-internal faucet from a host; baretopupfails DNS resolution.yacd listneeds-Ato show a network that lives in its own namespace.Notes
🤖 Generated with Claude Code