Bluefin Documentation Agent Guide#

Repository: projectbluefin/documentation

Production site: https://docs.projectbluefin.io/

Framework: Docusaurus 3.10.x, TypeScript, React 19, Node 24

Absolute boundary#

Agents edit content only. Agents never edit design.

Content includes prose, frontmatter, links, images, blog metadata, report data, and
registered content items inside existing components. Design includes layout,
CSS, component behavior, animation, page structure, JSX/HTML structure, routes,
and navigation. Do not change design to satisfy a content request.

If a request requires a new layout, visual treatment, component, animation, or
markup structure, stop and ask a maintainer. Do not implement it as a content edit.

Production site map#

The shipped entry point is build/index.html. It is generated output. Never edit
build/ directly. Edit the source file, then rebuild.

The documentation site uses the root route for the docs plugin. Production routes
are defined by sidebars.ts and the source files in docs/.

Blog discussion automation#

.github/workflows/open-discussion.yml creates the matching Giscus Discussion in
ublue-os/bluefin. It uses the existing repository secret
BLUEFIN_DISCUSSIONS_TOKEN; do not introduce a new token, GitHub App, or
cross-repository credential scheme. The secret must have Discussion write access
in ublue-os/bluefin. If it is unavailable, the workflow must fail explicitly
rather than report success without creating a discussion.

Follow docs/skills/giscus-discussions.md
when verifying, recovering, or archiving a blog discussion. Restore the existing
secret and rerun the workflow first; a maintainer may use the documented
GraphQL recovery only when the post is live and the normal workflow cannot
create the discussion.

• Getting Started: docs/index.md, introduction.md, downloads.mdx,
  installation.md, FAQ.md
• Using Bluefin: administration.md, tips.mdx, ai.md, command-line.md,
  images.md, driver-versions.mdx, troubleshooting.mdx
• Developer Experience: bluefin-dx.md, bluefin-gdx.mdx
• Specialized Editions and Hardware: lts.mdx, t2-mac.md, knuckle.md
• Community: contribution, testing, donations, project information, artwork,
  music, reports, and related pages listed in sidebars.ts
• Blog: blog/
• Monthly reports: reports/
• Custom pages: src/pages/

The production navbar also exposes Ask Bluefin, Blog, Changelogs, Reports, Hive,
Discussions, Feedback, and Store. Confirm a route in docusaurus.config.ts or
sidebars.ts before documenting it. Do not add a route or navigation item for a
feature that is not present in the source.

Editing content pages#

Edit Markdown or MDX in docs/. Preserve the existing frontmatter and page
structure unless the request is specifically about content metadata. Keep the
existing components and their props. Do not replace an existing component with
handwritten markup.

Use the site’s existing writing conventions:

• Use one H1 and H2 sections below it.
• Use imperative instructions for procedures.
• Use fenced code blocks with a language tag.
• Link to upstream documentation instead of copying generic Linux, GNOME,
  Flatpak, Podman, Distrobox, or Fedora reference material.
• State Bluefin-specific defaults and exceptions in this repository.
• Keep paragraphs short and remove claims that the source code does not support.

Do not introduce a new page when an existing page owns the topic. If a new page is
explicitly approved, add the source file, frontmatter, and sidebar entry without
changing sidebar styling or component behavior.

Editing blog posts and reports#

Blog edits change prose and metadata only. Do not change the blog layout, post
components, or CSS to present new content.

Blog posts live in blog/. Keep frontmatter valid. Add or update authors in
blog/authors.yaml when a post needs an author that is not registered.

Monthly reports live in reports/ and are generated by the report workflow. Edit a
report only when the task explicitly concerns generated report content. Do not
rewrite the report generator to change prose in one report.

Do not use future dates as a publishing mechanism. Keep an unfinished post
draft: true or unlisted: true until it is ready; remove that flag when it
should ship.

Registered artwork and dinosaur content#

The dinosaur character page is docs/dinosaurs.md. To add a character, edit that
file and add the character’s existing-format section:

1. Add the heading.
2. Add Name, Role, and Species fields.
3. Add the supplied image with Markdown image syntax.
4. Add the species link when one exists.
5. Keep the page’s existing order and wording style.

Do not edit src/components/ArtworkGallery.tsx, its CSS, or any other component
for a character addition. Do not invent a new card, grid, animation, image
placement, or metadata field. If the supplied asset needs a new visual treatment,
stop and ask a maintainer.

The artwork gallery page is docs/artwork.mdx and uses the existing
ArtworkGallery component. Its data comes from static/data/artwork.json, which
is generated. Do not hand-edit generated artwork data unless the task explicitly
changes the generator or registered artwork source.

Data-backed pages#

Several production pages render fetched or generated data. Edit the source and
pipeline, not generated output:

Content edits must not alter the components, CSS, fetch timing, API endpoints, or
fallback behavior. If the requested content cannot fit an existing data shape,
ask for a design decision instead of expanding the shape yourself.

Static assets#

Place site assets in static/img/ and reference them with root-relative paths such
as /img/example.webp. Use an existing asset slot and existing component. Do not
edit image dimensions, layout rules, responsive behavior, or asset presentation to
accommodate a new file.

Blog images live under static/img/blog/<post-slug>/. When a post ships the wrong
screenshot, overwrite the file in place and keep the existing filename so the
BlogFigure src, alt, and caption stay valid. Only edit the MDX when the
alt or caption no longer describes the new image. Do not add a second figure to
work around a wrong one.

Do not commit generated files from static/data/ or static/feeds/ unless the
file is a tracked CI seed explicitly listed in .gitignore. The SBOM seed files
are load-bearing and must remain present:

• static/data/sbom-attestations.json
• static/data/sbom-attestations-frontend.json

Build and validation#

Validation confirms content in the existing production design. It must not become
an excuse to change layout, styling, components, or behavior.

Install dependencies once:

npm install --legacy-peer-deps

Use the lightest checks that match the edit. Content changes should normally run:

npm run prettier-lint
npm run typecheck
npm run lint
npm test
npm run build

npm run build fetches data. Set GITHUB_TOKEN or GH_TOKEN when the fetch
scripts need authenticated GitHub API access. For a fast local preview after data
exists, use the repository’s just dev recipe.

Review the rendered page or generated HTML after the build. Confirm the requested
prose, link, image, or registered item appears. Do not fix a rendering issue by
changing design code during a content task.

Git and scope rules#

Work on a topic branch by default. Do not push directly to main on your own
initiative. Keep the change limited to content files and the required metadata or
data source. Do not include unrelated working-tree changes.

Before committing, inspect the exact staged paths and run the checks above. Use a
Conventional Commit such as docs: update dinosaur character list.

Remotes and production#

upstream is projectbluefin/documentation and is the production repository.
origin may be a personal fork; a fork branch never reaches production. Confirm
with git remote -v before pushing and target upstream for anything that must
ship.

Production is https://docs.projectbluefin.io/, deployed by
.github/workflows/pages.yml on every push to upstream/main. There is no
separate publish step. When a maintainer explicitly asks for a production update,
land the change on upstream/main; otherwise open a pull request.

Verify a live asset with a cache-busted request, because the CDN serves the old
copy for a while after a successful deploy:

curl -s -o /dev/null -w "%{http_code} %{size_download}\n" \
  "https://docs.projectbluefin.io/img/blog/<post>/<file>.png?cb=$RANDOM"

The repository also contains a CountMe Cloudflare Worker under
workers/countme-proxy/. It is a separate public service, not site content. Do
not touch it during a documentation or artwork edit. If a worker task is explicit,
follow its tests and deployment instructions in README.md; do not change site
design as part of that work.

Before changing anything#

Read the target source file and its nearby component or configuration. Check the
production build when a route or component is unclear. Search git history when an
existing content pattern has unclear ownership.

If the request conflicts with the content-only boundary, the production source,
or an existing data shape, stop and ask the maintainer. Do not guess and do not
create a parallel design.