{
  "id": "getting-started",
  "title": "Installation and commands",
  "description": "Install Aurelius and use its explicit commands to create, validate, preview, and publish documentation and visual sources.",
  "type": "guide",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "installation",
    "cli",
    "github"
  ],
  "related": [
    "home",
    "configuration",
    "publishing"
  ],
  "sourceRefs": [
    "../../cli.mjs",
    "../../package.json",
    "../../core/build.mjs",
    "../../core/scaffold.mjs"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Install the CLI as a development dependency\n\nFor a project that consumes Aurelius, install the newest semver-tagged GitHub release. npm resolves the newest release when you run this command. Commit the generated `package-lock.json` to pin the exact commit for local work and CI:\n\n```bash\nnpm install --save-dev github:ArthurWillers/Aurelius#semver:*\n```\n\nTo move an existing project to a newer release, run the install command again and commit both dependency files. Cloning the generator is only necessary for contribution or local customization.\n\nCommit the resulting `package.json` and `package-lock.json`, then use `npm ci` in CI. Private Git repositories require read access for both the developer and the CI token.\n\n## Clone only to contribute or customize\n\nClone the project when you intend to develop Aurelius itself, run its tests, or maintain a fork:\n\n```bash\ngit clone https://github.com/ArthurWillers/aurelius.git\ncd aurelius\nnpm ci\n```\n\nFor a temporary local integration test from another project, use `npm install --save-dev /absolute/path/to/aurelius`; avoid a global `npm link`, which makes the version less visible and harder to reproduce.\n\n## The command set\n\nCreate a starter site in a new or empty directory:\n\n```bash\nnpx --no-install aurelius init docs --title \"Product documentation\" --logo brand.svg\n```\n\nValidate sources without writing the publication:\n\n```bash\nnpx --no-install aurelius check --site docs\n```\n\nRebuild `docs/dist` from validated sources:\n\n```bash\nnpx --no-install aurelius build --site docs\n```\n\nPreview, watch source files, and reload the browser:\n\n```bash\nnpx --no-install aurelius dev --site docs --port 4173\n```\n\nList every named visual grammar:\n\n```bash\nnpx --no-install aurelius visual types\n```\n\nCreate an editable authored visual plus its semantic JSON envelope:\n\n```bash\nnpx --no-install aurelius visual init release-flow --site docs --kind sankey --format html\n```\n\nWithout `--logo`, `init` detects `logo.svg`, `logo.png`, `logo.jpeg`, or `logo.jpg` in the directory where you run it and copies the first match. Use `--logo` to select a specific SVG, PNG, JPEG, or JPG; when no default logo exists, `init` creates a small editable SVG placeholder.\n\nInside the Aurelius repository, use `npm run aurelius -- <command>`. For example:\n\n```bash\nnpm run aurelius -- check --site examples/product-docs\n```\n\n## A practical editing loop\n\n1. Edit Markdown, diagram JSON, authored HTML/SVG, assets, or `site.config.json`.\n2. Run `check` for structural errors.\n3. Use `dev` to review navigation, responsive layout, diagrams, and print output.\n4. Run `build` in CI or immediately before publication.\n\nNo server, database, or external account is required. Continue with [Site configuration](doc:configuration).",
  "sections": [
    {
      "id": "install-the-cli-as-a-development-dependency",
      "level": 2,
      "title": "Install the CLI as a development dependency",
      "text": "For a project that consumes Aurelius, install the newest semver-tagged GitHub release. npm resolves the newest release when you run this command. Commit the generated `package-lock.json` to pin the exact commit for local work and CI:   To move an existing project to a newer release, run the install command again and commit both dependency files. Cloning the generator is only necessary for contribution or local customization.  Commit the resulting `package.json` and `package-lock.json`, then use `npm ci` in CI. Private Git repositories require read access for both the developer and the CI token.",
      "line": 1
    },
    {
      "id": "clone-only-to-contribute-or-customize",
      "level": 2,
      "title": "Clone only to contribute or customize",
      "text": "Clone the project when you intend to develop Aurelius itself, run its tests, or maintain a fork:   For a temporary local integration test from another project, use `npm install --save-dev /absolute/path/to/aurelius`; avoid a global `npm link`, which makes the version less visible and harder to reproduce.",
      "line": 13
    },
    {
      "id": "the-command-set",
      "level": 2,
      "title": "The command set",
      "text": "Create a starter site in a new or empty directory:   Validate sources without writing the publication:   Rebuild `docs/dist` from validated sources:   Preview, watch source files, and reload the browser:   List every named visual grammar:   Create an editable authored visual plus its semantic JSON envelope:   Without `--logo`, `init` detects `logo.svg`, `logo.png`, `logo.jpeg`, or `logo.jpg` in the directory where you run it and copies the first match. Use `--logo` to select a specific SVG, PNG, JPEG, or JPG; when no default logo exists, `init` creates a small editable SVG placeholder.  Inside the Aurelius repository, use `npm run aurelius -- <command>`. For example:",
      "line": 25
    },
    {
      "id": "a-practical-editing-loop",
      "level": 2,
      "title": "A practical editing loop",
      "text": "1. Edit Markdown, diagram JSON, authored HTML/SVG, assets, or `site.config.json`. 2. Run `check` for structural errors. 3. Use `dev` to review navigation, responsive layout, diagrams, and print output. 4. Run `build` in CI or immediately before publication.  No server, database, or external account is required. Continue with [Site configuration](doc:configuration).",
      "line": 71
    }
  ],
  "sourcePath": "content/getting-started.md",
  "visuals": [],
  "apiVersion": 1
}