# Entity-Location Map

Canonical paths for everything a PA refers to. Paths under "Operator space", "PA run folder", "Work and projects", and "Session" are **relative to the operator repo root**; never hard-code the absolute value. Paths under "Platform package" are inside the installed `@stravica-ai/digital-operator-pa` package and accessed via `node` import resolution rather than absolute paths in the operator repo. See [working-directory.md](./working-directory.md).


## Operator space

| What | Where |
|---|---|
| Operator profile | `operator/profile/operator.json` |
| Operator knowledge | `operator/knowledge/` |
| Domain catalogue | `operator/knowledge/domains.json` |
| Operator notes | `operator/notes/` |
| Config / preferences | `operator/config/preferences.json` |
| PA memory (canonical) | `operator/memory/` |
| Operator extensions (roles) | `operator/extensions/roles/` |
| Operator extensions (tools) | `operator/extensions/tools/` |
| Operator extensions (blueprints) | `operator/extensions/blueprints/` |
| Operator extensions (workspace) | `operator/extensions/workspace/` |
| Extension manifest | `operator/extensions/manifest.json` |


## PA run folder

| What | Where |
|---|---|
| PA run folder | `agents/<paName>/` |
| PA staging | `agents/<paName>/staging/` |
| PA journal | `agents/<paName>/journal.md` |
| PA spawn log | `agents/<paName>/spawn-log.json` |
| PA learned rules | `agents/<paName>/learned-rules.md`; where the estate keeps one; never created when absent (rules are then synthesised into the operator's structured knowledge docs) |
| Next-session notes | `agents/<paName>/next-session.md` |
| Handover artefacts | `agents/<paName>/handover/<ts>.json` |
| PA memory (local cache) | `~/.claude/projects/<sanitised-project-path>/memory/` |


## Work and projects

| What | Where |
|---|---|
| Work items | `work/w-YYYY-MM-DD-NNN.json` |
| Projects | `projects/<id>/project.json` |
| Project progress trackers | `projects/<id>/progress.md` |


## Platform package

In v2 the platform code lives in `node_modules/@stravica-ai/digital-operator-pa/` (and its workspace-internal packages). Operator code addresses platform resources by package import path, never by an in-repo path.

**Resolving symbolic `@stravica-ai/engineering-pa-*` paths.** Platform docs (and the shipped CLAUDE.md template) reference bundled assets by symbolic package path, e.g. `@stravica-ai/engineering-pa-core/docs/…`. The internal packages are `private: true` and are never installed under their own names; the symbolic path resolves inside the wrapper's bundle:

```
@stravica-ai/engineering-pa-<pkg>/<subpath>
  → node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-<pkg>/<subpath>
```

| What | Resolved via |
|---|---|
| Core docs | bundled in `@stravica-ai/engineering-pa-core/docs/` |
| Core knowledge (bucket scaffolds) | bundled in `@stravica-ai/engineering-pa-core/knowledge/` |
| Desk CLI | `node_modules/.bin/desk` |
| Distill CLI | `node_modules/.bin/distill` |
| Memory-sync CLI | `node_modules/.bin/memory-sync` |
| Secrets CLI | `node_modules/.bin/secrets` |
| Sync CLI | `node_modules/.bin/sync` |
| Scheduler CLI | `node_modules/.bin/scheduler` |
| PA CLI | `node_modules/.bin/pa` |
| pa-init scaffolder | `node_modules/.bin/pa-init` |
| Research CLI | `node_modules/.bin/research` |
| Research runtime assets (workflow scripts, dispatch briefs, schemas) | resolved via `research paths --json` (`workflowsDir` / `briefsDir` / `schemaDir`); bundled under `@stravica-ai/engineering-pa-cli/src/research/{workflows,briefs,schema}/`. Never hard-code; the install path moves across version bumps. |
| Knowledge retrieval libs | `import('@stravica-ai/engineering-pa-core/src/knowledge/retrieval/*.mjs')` |
| Role definitions | bundled in `@stravica-ai/engineering-pa-core/roles/<role>/definition.md` |
| Standards docs | bundled in `@stravica-ai/engineering-pa-core/docs/standards/` |
| Schemas | bundled in `@stravica-ai/engineering-pa-core/schema/` |


## Operational artefacts (gitignored)

Per the tooling standard §16, per-host operational files must be in `.gitignore` and never committed:

| What | Where |
|---|---|
| Vault | `.vault/` (encrypted; key handled by secrets CLI) |
| Schedule definitions | `schedules/<id>.json` |
| Distill run logs | `.cache/distill/logs/` |
| Sync state | `.cache/estate-sync/` |
| Research sessions | `.cache/research/sessions/<sessionId>/` |


## Session

| What | Where |
|---|---|
| Session environment | `.session/environment.json` |