# Workspace

> Set up the monorepo. Find the correct source and check your change.

Use this guide to contribute to the products. Installing a product in another
application does not require cloning this workspace.

## Prerequisites

- Node.js **24.x**.
- npm **11.19.1**, matching the root `packageManager` field.
- Git and a feature branch.

```bash
git clone https://github.com/n3wth/n3wth.git
cd n3wth
git switch -c docs/my-change
npm install --global npm@11.19.1
npm ci
```

Run installation at the repository root. The root lockfile owns application and
shared-library dependencies. Do not fix a workspace resolution problem by
creating an app-local lockfile or installing another copy of UI.

## Find the right source

| Path | Responsibility | Start or validate |
| --- | --- | --- |
| `packages/ui` | Public `@n3wth/ui` package | `npm run check -w @n3wth/ui` |
| `apps/ui-docs` | Interactive UI documentation | `npm run dev:ui` |
| `apps/kit` | Kit registry and website | `npm run dev -w @n3wth/kit` |
| `apps/skills` | Skills catalog, installer, and CLI source | `npm run dev:skills` |
| `apps/r3-web` | r3 website and documentation | `npm run dev -w @n3wth/r3-web` |
| `packages/site-config` | Private shared origins and metadata helpers | `npm run check -w @n3wth/site-config` |
| `docs/developers` | This Docs7 documentation hub | `npx @upstash/docs7 dev docs/developers` |

The portfolio and Garden are also applications in this repository. Their public
content is not an installable developer product. r3's core server, Redis tests,
and package release workflow remain in [n3wth/r3](https://github.com/n3wth/r3).

## Build from the root

Root build commands build shared dependencies before their consumers:

```bash
npm run build:ui-docs
npm run build:kit
npm run build:skills
npm run build:r3
```

Use `npm run build` for all applications, and `npm run check` for the complete
workspace validation. `npm run check:metadata` expects build output; running it
before building will report missing files.

Applications import UI; UI owns its Astryx dependency and theme. Applications
must not import Astryx directly. Shared packages must not import applications.
Read the root and relevant package `AGENTS.md` before editing.

## Verify a change

1. Run the relevant package or app check while iterating.
2. Build the affected app through its root build command.
3. Run the complete checks required for shared changes. For route, layout, or
   packaging changes, run the relevant browser tests too.
4. Push a feature branch and wait for GitHub **Site CI** before merging.

UI changes can affect all six sites. Check both supported themes, mobile and
desktop layouts, first paint, code overflow, anchor links, and browser Back.
Pure edits to this hub use the [documentation checks](/publishing#validate-a-change).

## Releases and deployments

`@n3wth/ui` releases from 2.0.0 publish from this monorepo through
`publish-ui.yml` on a `ui-v*` tag. Bump the version and add a changelog entry
for consumer-facing library changes; do not run `npm publish` locally.
Documentation-only changes do not need a package release.

The six existing Vercel sites use automatic Git deployments. Docs7 is a separate
hosting connection to this same repository. Merging documentation is not evidence
that a Docs7 site has been connected or deployed; verify the hosted result.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| npm fails during peer resolution | Confirm `node --version` is 24.x and `npm --version` is 11.19.1; install from the root |
| An app cannot resolve UI output | Use the root app build command so shared packages build first |
| Unexpected duplicate React/UI behavior | Check workspace resolution with `npm ls @n3wth/ui react`; avoid nested registry copies |
| Metadata validation reports missing HTML | Build the relevant applications before checking generated metadata |
| r3 runtime tests are missing here | Run core development and tests in `n3wth/r3`, not `apps/r3-web` |

Source: [workspace instructions](https://github.com/n3wth/n3wth/blob/main/AGENTS.md),
[build scripts](https://github.com/n3wth/n3wth/blob/main/package.json), and
[UI release process](https://github.com/n3wth/n3wth/blob/main/docs/workspace/npm-release.md).