Getting Started

This guide walks you through everything you need to contribute to the Arda documentation site — from installing the required tools to getting your changes published. It is written for two audiences: humans making their first contribution, and AI agents helping a non-technical person contribute.

Tip

If you prefer a visual, point-and-click workflow over terminal commands, see Using VS Code or Antigravity for a complete walkthrough using the editor’s graphical interface for Git, branching, committing, and creating pull requests.

Prerequisites

Tools

You need the following tools installed on your machine:

• Git — version control. Download Git.
• Node.js (version 20 or later) — the JavaScript runtime that builds the site. Download Node.js.
• npm — the package manager, included with Node.js.
• A text editor — any editor that can open .md files works. Visual Studio Code and Antigravity are popular choices with built-in Markdown preview.
• A GitHub account — the source code is hosted on GitHub. Sign up at github.com if you don’t have one.

Tip

Agent note: If you are an AI agent assisting a human contributor, verify the prerequisites by running git --version and node --version in a terminal. If either is missing, guide the user through installation before continuing.

Terminal Access

Several steps in this guide require running commands in a terminal (also called a command line or shell). On macOS you have a few options:

• Terminal.app — the built-in terminal. Open it from Applications > Utilities > Terminal, or press Cmd + Space, type Terminal, and press Enter.
• VS Code integrated terminal — if you use Visual Studio Code, press Ctrl + ` (backtick) to open a terminal panel inside the editor. This is convenient because you can edit files and run commands in the same window.
• Antigravity integrated terminal — Antigravity includes a built-in terminal as well. Open it from the Terminal menu or the command palette.

Any of these will work for every command in this guide.

Verify Your Setup

Open a terminal and run:

git --version    # Should print git version 2.x or later
node --version   # Should print v20.x or later
npm --version    # Should print 10.x or later

If any command is not found, install the corresponding tool from the links above.

Step 0: Workspace Folder/Directory

It is highly recommended to create a directory dedicated to this and other projects you work on, particularly to facilitate the use of AI tools like Claude Code and Gemini CLI, or the Agent Assistants in Antigravity or VS Code.

Choose a place for your workspace folder, for example in your home directory create a subdirectory called arda or arda-workspace. This will be the root for your AI-assisted work.

mkdir ~/arda-workspace

If you want to enable AI assistants with pre-defined skills, rules, and agent profiles, you can follow the instructions in the Agentic Workspace repository.

Step 1: Clone the Repository

If this is your first time working with the project, clone the repository to your local machine:

cd ~/arda-workspace
git clone https://github.com/Arda-cards/documentation.git
cd documentation

If you already have the repository, make sure you are on the latest main branch:

git checkout main
git pull origin main

Step 2: Install Dependencies

From inside the documentation/ directory, install the project’s dependencies:

npm install

This creates a node_modules/ directory with all the packages the site needs. You only need to run this again when package.json changes.

Step 3: Start the Development Server

npm run dev

This starts a local server at http://localhost:4321. Open that URL in your browser to see the site. The server watches for file changes and reloads automatically — you can edit a page and see the result immediately.

Tip

Agent note: The dev server must stay running in its own terminal window while you edit. Open a second terminal for git commands and other operations.

Step 4: Create a Branch

The main branch of the repository is protected from direct updates (pushes). Never commit directly to main. Create a branch for your changes:

git checkout -b <username>/<short-description>

Replace <username> with your GitHub username and <short-description> with a few words about your change using lowercase and - as a separator. For example:

git checkout -b janedoe/fix-typo-in-personas

Note

Branch names should start with your GitHub username followed by a slash. This is a project convention.

Step 5: Edit or Create Content

Editing an Existing Page

All documentation content lives under src/content/docs/. Find the file you want to edit and open it in your text editor. Files are organized by section:

src/content/docs/
├── product/        # End-user documentation
├── domain/         # Domain model and concepts
├── current-system/ # Architecture and technical docs
├── process/        # Development workflows
├── about/          # Authoring guides (you are here)
└── ...

Each file starts with a YAML frontmatter block between --- markers. Do not remove or break this block — it contains metadata the site needs. Edit the content below the second ---.

Creating a New Page

1. Create a new .md file in the appropriate section directory.
2. Use kebab-case for the file name: my-new-topic.md.
3. Start the file with the required frontmatter:

---
title: "Your Page Title"
tags: [section-name, relevant-keywords]
domain: section-name
maturity: published
author: "Arda Systems"
---

4. Write your content below the frontmatter using standard Markdown.
5. Check that the page appears in the sidebar on the dev server. Some sections pick up new pages automatically; others require a sidebar configuration change. See Adding and Removing Sections for details.

Tip

Agent note: After creating a new file, check src/sidebar.json to determine whether the parent section uses autogenerate (new pages appear automatically) or explicit items (you must add the page’s slug to the array).

Formatting Quick Reference

What you want	Markdown syntax
Bold text	**bold**
Italic text	*italic*
Inline code	`code`
Code block	```language ... ```
Link to another page	[Link Text](other-page.md)
External link	[Text](https://example.com)
Image	
Bulleted list	- item (use -, not *)
Numbered list	1. item
Heading (section)	## Section Title
Heading (subsection)	### Subsection Title
Note callout	:::note … :::
Tip callout	:::tip … :::

For the full formatting reference, see the Authoring Guide and the Markdown Gallery.

Step 6: Preview Your Changes

With the dev server running, check your changes in the browser at http://localhost:4321. Verify that:

• The page renders without errors.
• Links work correctly.
• Headings, lists, and code blocks display as expected.
• The page appears in the sidebar (for new pages).

Step 7: Commit Your Changes

Once you are happy with your edits, save all files and commit:

git add src/content/docs/path/to/your-file.md
git commit -m "Add description of what you changed"

Tip

All Git operations (staging, committing, pushing, creating pull requests) can be done using the VS Code or Antigravity graphical interface instead of terminal commands. See Using VS Code or Antigravity for step-by-step instructions.

Caution

Only stage the files you changed. Avoid git add . which may include unintended files. If you changed multiple files, list them explicitly or use git add src/content/docs/ to limit the scope.

Write a short, descriptive commit message. Good examples:

• Add getting-started guide for new contributors
• Fix broken link in personas section
• Update inventory use case with new field descriptions

Step 8: Note your changelog entry (in the PR body, not CHANGELOG.md)

This repository uses PR-body changelogs. You do not edit CHANGELOG.md — CI will reject the PR if you do (see the manual-changelog label below for the rare exception). When the PR merges, a post-merge changelog-assembly workflow reads your entry from the PR description, computes the next version, prepends a release block to CHANGELOG.md, and creates a git tag + GitHub Release automatically.

At this step you don’t have to do anything yet — the PR template you’ll see in Step 10 has the placeholder ready. For now, decide which category (or categories) your change falls under:

Category	When to use	Version bump (semver)
Added	New pages, new sections	Minor (X.Y+1.0)
Changed	Restructured existing content	Major (X+1.0.0)
Fixed	Typos, broken links, corrections	Patch (X.Y.Z+1)
Removed	Deleted pages or sections	Major (X+1.0.0)
Deprecated	Content marked for future removal	Minor (X.Y+1.0)
Security	Security-related fixes	Patch (X.Y.Z+1)

The highest-priority category present in your PR drives the version bump (major > minor > patch). You can use more than one category in a single PR.

Tip

Agent note: Do not stage or edit CHANGELOG.md. Compose a ## CHANGELOG block in the PR body during Step 10. Choose the category that matches the change’s impact; the assembly workflow handles the version number.

Stage just your content changes:

git add src/content/docs/path/to/your-file.md
git commit -m "Add description of what you changed"

For background on the model (PR body convention, post-merge assembly, the merge queue, the arda-changelog-bot identity that owns the assembly commits, and the path-scoped reviewer policy), see Queued CI/CD.

Step 9: Push Your Branch

Push your branch to GitHub:

git push -u origin <your-branch-name>

The -u flag sets up tracking so future pushes only need git push.

Step 10: Create a Pull Request

1. Go to the repository on GitHub: https://github.com/Arda-cards/documentation.
2. GitHub will show a banner offering to create a pull request from your recently pushed branch. Click Compare & pull request.
3. The PR description is prefilled by the repo’s PR template (.github/pull_request_template.md). It has four sections:
   • ## Summary — short description of what changed and why.
   • ## CHANGELOG — one or more category blocks (### Added, ### Fixed, etc.) each with at least one bullet entry. This block is required; the changelog-check workflow will fail the PR if it’s missing or empty.
   • ## Closes — optional, links any issues this PR closes.
   • ## Verification — what you checked locally (make pr-checks passes, preview deploy looks right, etc.).
4. Edit the Title to a short summary of your change.
5. Click Create pull request.

Alternatively, create the PR from the command line using the GitHub CLI (the template auto-fills the body):

gh pr create
# Or, to override the title:
gh pr create --title "Your PR title"

Caution

Do not erase the ## CHANGELOG block in the PR description, and do not edit CHANGELOG.md in your commits. Both are enforced by the changelog-check workflow. If you need a manual hand-edit to CHANGELOG.md (rare — e.g., correcting a historical entry), add the manual-changelog label to the PR so the check allows it.

Tip

Agent note: Use gh pr create without --body so the template loads automatically. Then edit the body with gh pr edit <pr-number> --body "$(cat body.md)" if you need to refine the ## CHANGELOG block.

Amending your changelog after the PR is open

If you need to revise the ## CHANGELOG section after the PR has been created, post a comment on the PR containing an updated ## CHANGELOG block. The post-merge assembly reads the last ## CHANGELOG block found (PR body first, then author comments in chronological order), so the latest comment wins. This avoids editing the PR description or pushing a new commit just to fix the entry.

Step 11: CI Checks and Review

After you create the PR, the CI pipeline will automatically run these required status checks:

1. changelog-check — validates that your PR body contains a ## CHANGELOG section with valid categories, and rejects the PR if it modifies CHANGELOG.md (unless the manual-changelog label is set).
2. review-required-gate — passes by default; only fails if the REVIEW-REQUIRED label is set and no approving human review exists.
3. Build preview — compiles the site, runs the link check across all pages, and runs the Playwright smoke tests.

Plus one deploy step (not a required check, but you’ll want to look at it):

• deploy-preview — publishes your changes to a preview Pages environment at arda-cards.github.io/documentation. Share this link with reviewers so they can see the rendered pages. Each push to your branch updates the preview.

The production publish at arda-cards.github.io happens automatically after your PR merges — the changelog-assembly workflow prepends your entry to CHANGELOG.md and tags a release, then build-production + deploy-production push the site to the org-level Pages.

Who needs to approve

The reviewer requirement is path-scoped via CODEOWNERS:

• Roadmap-only PRs (only files under src/content/docs/roadmap/) — no approval is required. Your CI checks must still pass, but you can merge yourself.
• Any other path — an approving review from a member of @Arda-cards/engineering is required. Bot approvals do not satisfy this requirement; a real human must approve.

Labels you can apply

Label	Effect
auto-merge	Enables GitHub auto-merge. Once all required checks pass and (if required) a human reviewer has approved, the PR enters the merge queue and merges automatically.
REVIEW-REQUIRED	Forces a human approving review even on roadmap-only PRs. Use when you want a second pair of eyes on a sensitive change.
manual-changelog	Allows the PR to edit CHANGELOG.md directly, bypassing the changelog-check rejection. Rare — use only for genuine hand-edits like backfilling a historical entry. The post-merge assembly workflow detects the hand-edit and skips assembly for that commit so the file isn’t double-written.

You can add labels when creating the PR or at any time before merge. Removing a label reverses its effect.

Concurrent PRs and the merge queue

auto-merge enters the PR into GitHub’s native merge queue rather than merging immediately. The queue lets multiple approved PRs land in a single batch when their checks all pass on the synthetic merge commit, without requiring authors to rebase one against the other. Because CHANGELOG.md is never edited in PRs, two simultaneous PRs no longer conflict on that file — both can land in the same queue batch, and the assembly workflow runs once per merge (serialized by a concurrency group) to produce consecutive version entries.

See Queued CI/CD for the full pipeline reference, including the per-repo configuration table (documentation uses merge_method: MERGE so your author commits are preserved on main).

Step 12: Steward your PR through to merge

After the PR is open and checks have run, your remaining job is to:

1. Verify the preview — open the URL from the deploy-preview job (also linked in the PR’s “Deployments” sidebar) and click through the pages you changed. The link check + smoke tests catch structural issues, but they don’t verify your prose reads well.
2. Wait for / request review if your PR touches anything outside src/content/docs/roadmap/. The PR’s “Reviewers” sidebar shows the team handle (@Arda-cards/engineering) auto-requested via CODEOWNERS.
3. Resolve every review thread — branch protection requires all conversations to be resolved before merge. Use the “Resolve conversation” button on each thread once the comment has been addressed (either by a fix commit or a reply).
4. Add auto-merge when you’re ready. The PR enters the merge queue once all required checks are green and (if needed) approval is in. You don’t need to be at the keyboard for the merge itself.
5. If the queue rejects your PR, GitHub posts a comment on the PR explaining why (usually a check failure on the synthetic merge commit, often a stale base). Fix the cause, push, re-apply the auto-merge label, and the queue tries again.
6. After merge, the post-merge automation handles the rest:
   • changelog-assembly writes your release block to CHANGELOG.md, tags the commit, creates the GitHub Release. This commit is authored by arda-changelog-bot[bot].
   • build-production + deploy-production push the site to arda-cards.github.io.
   • You can confirm completion by checking the Actions tab for two successful runs after your merge — one assembly, one production deploy.

If anything in this sequence stalls (a check stuck pending, a queue rejection you don’t understand, an assembly run that failed), open the failing job’s logs and read from the bottom — most failures are self-explanatory. If you’re still stuck, ping the engineering team with a link to the failing run.

Common Tasks Cheat Sheet

Task	Command
Install dependencies	npm install
Start dev server	npm run dev
Build the site	npm run build
Preview built site	npm run preview
Create a branch	git checkout -b username/description
Stage specific files	git add path/to/file.md
Commit	git commit -m "message"
Push branch	git push -u origin branch-name
Create PR (CLI)	gh pr create (template auto-loads; edit body if needed)
Run pre-push checks	make pr-checks
Enable auto-merge	Add the auto-merge label on the PR
Force human review	Add the REVIEW-REQUIRED label on the PR
Allow CHANGELOG.md edit	Add the manual-changelog label (rare)
Amend changelog entry	Post a PR comment with an updated ## CHANGELOG block (last one wins)

Troubleshooting

npm install fails — Make sure you are using Node.js 20 or later. Run node --version to check. If you recently updated Node, delete node_modules/ and package-lock.json, then run npm install again.

Dev server won’t start — Check that port 4321 is not already in use. Stop any other dev servers, then try again.

Page doesn’t appear in the sidebar — The parent section may use explicit sidebar items. Check src/sidebar.json and add your page’s slug if needed. See Adding and Removing Sections.

Build fails with link errors — You may have a broken link. Check the build output for the file and line causing the error. Make sure all internal links use relative paths with the .md extension.

git push is rejected — Your local branch may be behind main. Run git pull origin main --rebase then push again.