# Use and adapt ai-p1

Use the documented interfaces and source layout for **ai-p1**. The sections below retain the README’s examples and configuration details.

## Common commands

| Command | Purpose |
| --- | --- |
| `npm run build` | Build workspaces that expose a build command |
| `npm run test` | Run workspace test commands |
| `npm run typecheck` | Type-check participating workspaces |
| `npm run licenses:check` | Validate the separate dependency-license inventory |
| `npm run licenses:project:check` | Validate Qentrah licensing, package guards, and asset boundaries |
| `npm run publication:check` | Run the strict release gate; expected to fail until legal approval is recorded |
| `npm run docs:codebase-map` | Regenerate the interface inventory |
| `npm run docs:codebase-map:check` | Confirm the committed interface inventory is current |
| `npm run brand:assets` | Generate Qentrah-branded runtime assets from the canonical brand owner |
| `npm run assets:public` | Generate neutral placeholders for non-brand public media |

Focused Workspace verification:

```bash
npm --workspace @qentrah/workspace run typecheck
npm --workspace @qentrah/workspace run test:agency-readiness
npm --workspace @qentrah/workspace run check:convex-runtime
```

## Local development

### Requirements

- Node.js 22 or later
- npm
- Service credentials for the application surface being run

Install the workspace from the repository root:

```bash
npm ci
```

Copy only the relevant committed environment examples and provide local values. Do not commit `.env` files, credentials, production identifiers, or customer data. See [setup and configuration](https://github.com/Up-to-code/ai-p1/blob/main/docs/operations/setup-and-configuration.md) for the current environment contract.

Start a product surface:

```bash
npm run dev:ws                  # Workspace web app and Convex development runtime
npm run dev:workspace:desktop   # Workspace desktop development shell
npm run dev:marketing           # Marketing site on port 3005
npm run dev:mobile              # Expo mobile development server
npm run dev:zapier              # Zapier integration development server
```

`apps/partners` is a retained static surface rather than an executable npm workspace.

## Commands in the root manifest

The captured [package.json](https://github.com/Up-to-code/ai-p1/blob/HEAD/package.json) declares the following scripts. Run them from the directory containing that manifest.

| Command | Script |
| --- | --- |
| `npm run build` | `npm run build --workspaces --if-present` |
| `npm run test` | `npm run test --workspaces --if-present` |
| `npm run typecheck` | `npm run typecheck --workspaces --if-present` |

## Troubleshoot a local change

1. Reproduce the smallest example from the [quick-start guide](/docs/up-to-code-ai-p1/quick-start-guide).
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

## Source and help

- [GitHub repository](https://github.com/Up-to-code/ai-p1)
- [Original README](https://github.com/Up-to-code/ai-p1/blob/main/README.md)
- [Issues and existing reports](https://github.com/Up-to-code/ai-p1/issues)