# Projects

Project structure, manifest, and artifact storage

Canonical URL: https://docs.paradoc.dev/cli/projects/

A project is a directory managed by the CLI. It contains a manifest that describes the project, a state directory that tracks installed artifacts, and the artifact files themselves. Initialize one with [`paradoc init`](/cli/commands/init).

## Initializing a project

```bash
paradoc init
```

In interactive mode, the CLI first prompts for the target directory, then the project title, description, and visibility (public or private). Use `--yes` to skip prompts:

```bash
paradoc init --yes --name "My Project" --visibility private
```

See the [`init`](/cli/commands/init) command reference for all options.

## The project manifest

The `paradoc.json` file in the project root defines your project:

```json
{
  "$schema": "https://schema.paradoc.dev/manifest.json",
  "name": "@your-org/my-project",
  "title": "My Project",
  "description": "A description of your project",
  "visibility": "private",
  "artifacts": {
    "dir": "artifacts",
    "output": "json"
  },
  "registries": {
    "@acme": "https://registry.acme.com"
  },
  "security": {
    "allowedContentTypes": ["application/vnd.acme.form+json"]
  },
  "cache": {
    "ttl": 3600,
    "directory": ".cache/paradoc"
  }
}
```

### Fields

| Field         | Type                      | Required | Description                              |
| ------------- | ------------------------- | -------- | ---------------------------------------- |
| `$schema`     | string                    | No       | JSON schema URL for editor validation    |
| `name`        | string                    | Yes      | Project identifier in `@org/name` format |
| `title`       | string                    | Yes      | Human-readable project title             |
| `description` | string                    | No       | Project description                      |
| `visibility`  | `"public"` \| `"private"` | No       | Project visibility (default: `private`)  |
| `artifacts`   | object                    | No       | Artifact storage configuration           |
| `registries`  | object                    | No       | Registry configuration by namespace      |
| `security`    | object                    | No       | Download settings                        |
| `cache`       | object                    | No       | Cache configuration overrides            |

### Artifacts

Controls where artifacts are stored and in what format.

| Field              | Default       | Description                                                   |
| ------------------ | ------------- | ------------------------------------------------------------- |
| `artifacts.dir`    | `"artifacts"` | Directory for downloaded artifacts (relative to project root) |
| `artifacts.output` | `"json"`      | Default output format (see [Output formats](#output-formats)) |

### Registries

Maps namespaces to registry URLs. See [Registries](/concepts/registries) for details.

### Security

| Field                          | Description                                                                                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `security.allowedContentTypes` | Content types added to the built-in download defaults. Project values replace global additions but cannot narrow the built-in defaults. Blocked types are never allowed |

### Cache

| Field             | Default              | Description                                                   |
| ----------------- | -------------------- | ------------------------------------------------------------- |
| `cache.ttl`       | `3600`               | Time in seconds before cached registry data expires           |
| `cache.directory` | `"~/.paradoc/cache"` | Cache directory. Relative paths resolve from the project root |

## Directory structure

After initialization and installing an artifact, your project looks like this:

```
my-project/
├── paradoc.json          # Project manifest
├── .paradoc/                   # CLI state directory
│   └── lock.json
└── artifacts/              # Downloaded artifacts
    └── @acme/
        └── residential-lease.yaml
```

## The `.paradoc/` directory

The `.paradoc/` directory stores internal CLI state. Together with `paradoc.json`, it marks the project root. `paradoc init` creates it empty. You should not edit its files directly — the CLI manages them.

| File        | Purpose                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------- |
| `lock.json` | Record of installed artifact editions and versions, source URLs, and integrity checksums |

## The lock file

`.paradoc/lock.json` records the version, source URL, and integrity checksum written by `paradoc add` for each installed artifact. For an artifact that has editions, it also records the key of the installed edition. Each entry is keyed by `@namespace/name`. The CLI does not use the lock file to restore or pin a later install.

## Output formats

The CLI supports four output formats for artifact files. Set the default in `artifacts.output` in the manifest, or override it for one install with `paradoc add --output`.

| Format  | Extension         | Description                                                                   |
| ------- | ----------------- | ----------------------------------------------------------------------------- |
| `json`  | `.json`           | Standard JSON. Portable and widely supported.                                 |
| `yaml`  | `.yaml`           | YAML. Easier to read and edit by hand.                                        |
| `typed` | `.json` + `.d.ts` | JSON file with a companion TypeScript declaration file for type-safe imports. |
| `ts`    | `.ts`             | Standalone TypeScript module with the artifact embedded as `as const`.        |

The `typed` and `ts` formats are generated by [`paradoc generate`](/cli/commands/generate) or by passing `--output typed` or `--output ts` to [`paradoc add`](/cli/commands/add).

Use `json` or `yaml` if you don't need TypeScript integration. Use `typed` if you want type-safe imports without changing your JSON source files. Use `ts` for a single self-contained module.