docs: add MkDocs documentation site with Diátaxis structure#91
docs: add MkDocs documentation site with Diátaxis structure#91jmgilman wants to merge 15 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:
Both analyses are clean from a critical-risk standpoint. The dependency analysis found no pinned version dependency changes requiring review. The code analysis identified one actionable medium-severity finding: the actions/checkout step in .github/workflows/docs.yml does not set persist-credentials: false, which means Git credentials unnecessarily persist in the runner environment after checkout. The overall risk remains low because the workflow already operates under minimal permissions (contents: read) and all actions are pinned to full commit SHAs, limiting the blast radius of any potential credential exposure. The WebSocket (ws://) findings were confirmed false positives present only in Markdown documentation. We recommend adding persist-credentials: false to the actions/checkout step as a best-practice hygiene improvement before or shortly after merging: - uses: actions/checkout@de0fac2 with: persist-credentials: false Note View full detailed analysis result for more information on the output and the checks that were run.
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 |
Kusari flagged the docs Pages workflow's actions as pinned to mutable tags (elevated risk given pages:write/id-token:write on the deploy job). Pin all five to commit SHAs, matching the repo's existing convention (reusing the actions/checkout v6.0.2 pin).
|
Kusari PR Analysis rerun based on - 406dabf performed at: 2026-06-06T22:17:30Z - link to updated analysis |
Pages is enabled with the GitHub Actions source; the site publishes at https://meigma.github.io/yacd/. Set site_url so canonical links and the generated sitemap use the correct base.
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