# @stravica-ai/digital-operator-pa

The public, single-bundled npm surface of the engineering-PA platform.

One install gives operators every CLI bin and bundles the internal platform
code into a self-contained tarball.

## Install

```sh
pnpm add @stravica-ai/digital-operator-pa
```

Requires Node 24+. The package is public on `registry.npmjs.org` and needs no
registry auth. See [`./docs/installing.md`](./docs/installing.md) for the
full install guide.

New to the platform and setting up a single-person PA on one laptop? Follow
[`./docs/onboarding-solo.md`](./docs/onboarding-solo.md) — a
ten-minute walkthrough from an empty directory to a working PA under your
own Claude Code subscription.

Want a plain-language tour of what the PA does before you install it? Read
[`./docs/what-it-can-do.md`](./docs/what-it-can-do.md) — a day-to-day view
of the capabilities, how it learns you, and what is (and is not) in this
release.

## Bins

The wrapper exposes the platform's operator-facing CLIs:

| Bin               | What it does                                                |
|-------------------|-------------------------------------------------------------|
| `pa`              | Top-level operator CLI (`pa status`, `pa workspace`, …)     |
| `desk`            | Task + project queries                                      |
| `launch`          | Boot a scoped agent instance bound to an identity and task  |
| `sync`            | Per-host single-writer git sync                             |
| `secrets`         | SOPS+age secrets vault management                           |
| `scheduler`       | Scheduling primitives (cron / launchd install + verify)     |
| `smoke`           | Fresh-clone smoke suite                                     |
| `distill`         | Librarian distillation sweep                                |
| `memory-sync`     | PA-memory cache mirror                                      |
| `migrate-inspect` | Host inspection for migration planning                      |
| `pa-init`         | Scaffolder for a new operator repo                          |
| `slice`           | Operator profile slice generator (compact boot context)     |
| `pa-coordinator-hook` | Claude Code `PreToolUse` hook — three-tier coordinator-mode tool policy |

Each bin runs `--help` and exits 0 to confirm the install is healthy.

`pa-coordinator-hook` is the exception to "operator-facing CLI" above — it's
a hook binary invoked by Claude Code itself, not run by hand. See
[`../cli/docs/coordinator-hook.md`](../cli/docs/coordinator-hook.md) for the
full contract, the settings.json wiring snippet, and the per-PA overlay
mechanism.

### Starting a PA session

After `pa-init` lays down an operator repo, kick off your PA with:

```sh
cd <operator-repo>
pa session
```

`pa session`:

1. Resolves the operator repo root (`$DAVE_REPO_ROOT` → `$PA_REPO_ROOT`
   → `.git`-walk → CWD).
2. Reads `operator/config/preferences.json` and pulls out `paName`.
3. Chdirs to `agents/<paName>/`.
4. Execs `claude --dangerously-skip-permissions`, inheriting stdio.

For muscle memory, alias it to your PA's name:

```sh
alias dave='pa session'    # add to ~/.zshrc / ~/.bashrc
```

Now `dave` alone boots a session. Errors (missing preferences, missing
agent directory, `claude` not on `PATH`) exit non-zero with a concrete
remediation message.

## Programmatic surface

```js
import { name, version, bins, bundled, describe } from '@stravica-ai/digital-operator-pa';

console.log(describe());
// → { name: '@stravica-ai/digital-operator-pa', version: '0.1.1', bins: [...], bundled: [...] }
```

For richer in-process composition (importing internal modules directly),
consumers can reach into the bundled `dist/` tree — but the bin shims are
the supported contract.

## Single-bundled-publish model (approach A2)

`@stravica-ai/digital-operator-pa` ships **one tarball** that contains:

```
package/
  package.json           # bin map, exports, publishConfig
  index.mjs              # public ESM surface
  bin/                   # bin shims — thin wrappers over dist/.../cli.mjs
  dist/                  # bundled internal packages (built by build.mjs)
    engineering-pa-core/
    engineering-pa-runbook/
    engineering-pa-cli/
    engineering-pa-migrate-inspect/
    engineering-pa-workspace/
    engineering-pa-scaffold/
    engineering-pa-librarian/
    engineering-pa-types-engineering/
    engineering-pa-core-extensions-atlassian/
    engineering-pa-core-extensions-n8n/
  README.md
  LICENSE
```

`build.mjs` is the pre-pack bundler. It:

1. Copies each internal workspace package's source into `dist/<short-name>/`,
   skipping `test/`, `node_modules/`, `dist/`, IDE state.
2. Rewrites every `'@stravica-ai/engineering-pa-*'` string literal inside copied
   `.mjs` files to a relative path within `dist/`, so cross-package imports
   resolve without any runtime npm-name lookup.

Hooked via `prepack`, so `pnpm pack` and `pnpm publish` always run it first.
Also exposed as `pnpm --filter @stravica-ai/digital-operator-pa run build`.

### Bundled docs, knowledge, roles, and schemas

The `dist/` tree carries each internal package's non-code assets too — for
core that means `docs/`, `knowledge/` (bucket scaffolds), `roles/`, and
`schema/` all ship inside the tarball.

Platform documentation refers to these assets by **symbolic package path**
(e.g. `@stravica-ai/engineering-pa-core/docs/pa-operating-model.md`). The
internal packages are `private: true` and never installed under their own
names, so that path does not exist in `node_modules` verbatim. In an operator
install it resolves inside the wrapper's bundle:

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

For example, `@stravica-ai/engineering-pa-core/knowledge/content-voice/` lives at
`node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/knowledge/content-voice/`
relative to the operator repo root.

**Why A2 over A1.** A1 publishes each internal package separately and the
wrapper depends on them via the registry. That requires every internal to be
public (or at least published with auth-token coverage), multiplies the
operator-side auth surface, and creates N-tarballs-per-release coordination.
A2 keeps internals `private: true`, ships one auditable artefact, and matches
the v0.1 brief explicitly. Split to A1 later only if multi-version internal
publishing becomes a real need.

## Scripts

```sh
pnpm --filter @stravica-ai/digital-operator-pa run build         # populate dist/
pnpm --filter @stravica-ai/digital-operator-pa run test          # wrapper-level tests
pnpm --filter @stravica-ai/digital-operator-pa run dry-publish   # build + dry-publish
pnpm --filter @stravica-ai/digital-operator-pa pack              # produce a real tarball
```

## Publish target

`publishConfig.registry` points at `https://registry.npmjs.org/` with
`access: public`. Publishes are manual (run by a maintainer with npmjs publish
rights) from this directory: `pnpm publish` triggers `build.mjs` via `prepack`,
then ships the bundled tarball to npmjs.org. `ci.yml`'s `dry-publish` job proves
the pack/publish mechanics on every push. See [`./docs/installing.md`](./docs/installing.md)
for the release-pipeline section.

### Retired predecessor

The prior identity of this codebase was `@stravica/engineering-pa` on GitHub
Packages (`https://npm.pkg.github.com`, scope `@stravica`). That package is
retired as of 2026-07-30; its final version (`0.6.2`) is a republish of `0.6.1`
carrying a deprecation notice. Note the scope difference from `@stravica-ai`
(the current package) and from `@stravica-ai/engineering-pa-core`, which is a
separate live package and is unaffected.

## Standards

- JS only — `.mjs`, `type: module`.
- Zero runtime npm dependencies.
- `node:test` for tests.
- camelCase JSON.
- MIT licensed.