This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.
- Add durable project-specific notes here as they are discovered through real work.
hugo alone fails with binary with name "postcss" not found in PATH. Run npm install
once, then build with the local binaries on PATH:
npm install
PATH="$PWD/node_modules/.bin:$PATH" hugo -d <outdir>
npm run build (see package.json scripts) does the same via the pinned Hugo.
When a page moves or an external system links to a URL this site no longer serves, add the
dead path to the page's aliases: front matter rather than leaving a 404 - Hugo emits a
redirect stub for each one. content/en/kanvas/operator/_index.md and
content/en/kanvas/operator/views/index.md are the working examples. Verify after a build
by checking the generated <outdir>/<dead-path>/index.html for the url= refresh target.
Heading anchors are linked from outside this repo too, so renaming a heading silently breaks
those links. The Layer5 Cloud UI hardcodes some of them: MAIL_DOCS_URL in
meshery-cloud's ui/components/identity/org-management/org-smtp-tab.tsx points every
"Learn more" link on the Email tab at
/cloud/guides/organizations/org-management/#configuring-your-own-mail-server. Grep
meshery-cloud's ui/ for docs.layer5.io before renaming a heading on a cloud guide. Goldmark heading attributes are enabled: keep the old anchor by writing
### New Wording {#old-anchor-slug}. To prove no anchor was lost, build master and your branch
to separate directories and diff the id= attributes of every <h1>-<h6> across both trees;
content/en/cloud/academy/creating-content/building-certifications/index.md is a worked example.
Several index.md files end without a trailing newline, and some end inside a raw HTML
block. Appending a Markdown heading directly after a closing </div> leaves it unparsed and
rendered as literal ## text. Always leave a blank line between raw HTML and following
Markdown, and check the built HTML for the heading's id= anchor.
A literal backslash inside inline HTML is a related trap: Goldmark reads the \< in
<button>\</button> as an escaped < and the tag never closes. Write the key as \
(content/en/kanvas/reference/keyboard-shortcuts.md is the worked example) and confirm the
built HTML, not the source, before committing.
The cloud guides describe a product that lives in meshery-cloud, so every product claim is
verified against origin/master there, never against a summary. The screen strings are in
ui/components/identity/org-management/; the behavior behind them is in server/handlers/.
That repo's own docs/reference/ and docs/runbooks/ are the best starting point but are not
the arbiter - they have described behavior the handlers do not implement. Confirm a capability
has a producer in the Go or TSX before writing it up: a contract enum member or a runbook
sentence is not proof the feature ships.
meshery-cloud is a PRIVATE repository, so never link one of its pull requests, issues or
files from a content page - the link 404s for every reader of docs.layer5.io. Cite the released
version instead (v1.0.253), which an operator can check against their own deployment, and keep
the pull-request reference in the commit message and the docs pull request, where the audience
can open it.
Behavior can also disagree with data/openapi.yml. The server is the arbiter for what a
response looks like: that file declares 401 as text/plain on every route, while any handler
behind AuthorizationMiddlewareForAdmin answers echo.NewHTTPError, which echo serializes as
JSON. Document what the handler sends and flag the specification.
Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.