---
title: "Ownership"
description: "Which files are yours and which are the framework's, and what that means for customizing and upgrading."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ownership

A Nimbus site has two layers. Read this before changing a component or a layout, so you know what an upgrade will and won't touch.

## Your files and the framework's

Everything the scaffolder writes into your repo is yours: components, layouts, routes, styles and content. Change any of it. Nothing overwrites your files: upgrading the package leaves them alone, and Nimbus offers upstream changes to them as diffs you choose to take. [Project structure](/project-structure) maps each file and where the framework's part begins.

The `@cloudflare/nimbus-docs` package's exports are a stable contract, versioned with semver: a breaking change comes with a migration, which `nimbus-docs migrate` applies or explains. [Package API](/styling/package-api) lists the helpers your files call.

## The ladder

Customize at the lowest rung that does the job, since each rung up is more of your own code to maintain:

1. **Configuration.** Options in `astro.config.ts`, such as the sidebar, search and rendering. See [Configuration](/reference/configuration).
2. **Tokens.** Colours, type and spacing in `src/styles/globals.css`. See [Theme and tokens](/styling/theme-and-tokens).
3. **Components from the registry.** Install with `nimbus-docs add`; they land as files you own. See [Add components and features](/styling/add-components).
4. **Editing a file.** Change a component, layout or route directly.
5. **Your own components.** Write new ones and use them in MDX. See [Custom components](/styling/custom-components).

## Staying current

Upstream changes to files you own arrive as changes you review:

| Command | What it does |
| --- | --- |
| `nimbus-docs outdated` | Lists starter files, registry components and package API work that changed upstream. `--to <templates-vX.Y.Z>` compares against a specific release. |
| `nimbus-docs diff <file>` | Shows the upstream change to one starter file next to yours. `--apply` takes it when you haven't edited the file. |
| `nimbus-docs add <slug> --overwrite` | Reinstalls a registry component, asking before it replaces one you've edited. |
| `nimbus-docs migrate` | Applies package API migrations and lists the upgrade reviews for your new version. |
| `nimbus-docs init` | Writes `nimbus.json` for a project that doesn't have one, so the commands above know where it started. |

`outdated` and `diff` download the starter from GitHub. If GitHub rate-limits you, set `GIGET_AUTH` to a GitHub token; see [Troubleshooting](/publish/troubleshooting#github-rate-limited-the-template-download-http-403).

[Upgrade Nimbus](/publish/upgrading) puts these in order for a release.

Source: https://nimbus-docs.com/styling/how-customization-works/index.mdx