picagear 0.1.0-next.0

package/docs/local-installation.md

@@ -0,0 +1,85 @@
+# Installation
+
+Picagear `0.1.0-next.0` is a preview. It can be installed from the npm registry under the `next` tag, or from a reviewed local archive. Both paths install Picagear as a development dependency of a private consumer project with package scripts disabled. This procedure makes no global installation claim.
+
+The preview is a functional foreground command line tool. It never merges a pull request and never deletes a worktree. A full lifecycle system integration run against the installed package and live task performance with real providers are not yet proven.
+
+Picagear is licensed under the [PolyForm Strict License 1.0.0](../LICENSE). It permits use for noncommercial purposes as the license defines them. It does not grant rights to distribute the software or to make changes or new works based on it. Public availability on npm does not grant further rights. Read the license text for the full terms.
+
+## Install the npm preview
+
+Use Node 22.13 or later, npm, and Git. Create or select a private consumer project that is separate from any Picagear source checkout.
+
+```sh
+cd <consumer-directory>
+npm init --yes
+npm pkg set private=true --json
+npm install --save-dev --ignore-scripts picagear@next
+./node_modules/.bin/picagear --help
+./node_modules/.bin/picagear init --repo <path> --adapters codex,claude
+```
+
+This installs Picagear only. Decadra advisory integration is optional and is installed separately from a reviewed local archive as described below. The Decadra package currently published on npm does not provide that integration.
+
+## Local archive installation
+
+Picagear and Decadra can be installed together from reviewed local archives. This remains a supported local installation path and does not depend on either registry.
+
+### Required inputs
+
+Use Node 22.13 or later, npm, Git, and a user selected consumer directory that is separate from both source checkouts. The current package versions are Picagear `0.1.0-next.0` and Decadra `0.4.1`.
+
+The artifact coordinator creates both archives outside the repositories after review. Each archive record must contain all of these values from the same generation run:
+
+| Field            | Required value                                                            |
+| ---------------- | ------------------------------------------------------------------------- |
+| Source           | Repository identity and exact final Git revision                          |
+| Dirty status     | Empty output from `git status --short`                                    |
+| Lock input       | SHA256 of the committed `package-lock.json`                               |
+| Package identity | Name and version read from the packed manifest                            |
+| Archive          | Filename, byte size, SHA256, npm integrity, Node version, and npm version |
+
+A filename or version alone is not provenance. Do not copy a digest from an earlier build, and do not describe an archive as retained evidence until the exact bytes and record have actually been retained.
+
+### Generate reviewed archives
+
+Choose an artifact directory outside both repositories. Confirm each checkout is at its approved final revision and clean. Build, then pack the existing build with package scripts disabled.
+
+```sh
+git -C <picagear-checkout> rev-parse HEAD
+git -C <picagear-checkout> status --short
+npm --prefix <picagear-checkout> run build
+npm pack <picagear-checkout> --ignore-scripts --pack-destination <artifact-directory> --json
+
+git -C <decadra-checkout> rev-parse HEAD
+git -C <decadra-checkout> status --short
+npm --prefix <decadra-checkout> run build
+npm pack <decadra-checkout> --ignore-scripts --pack-destination <artifact-directory> --json
+
+shasum -a 256 <picagear-checkout>/package-lock.json <decadra-checkout>/package-lock.json
+shasum -a 256 <artifact-directory>/picagear-0.1.0-next.0.tgz <artifact-directory>/decadra-0.4.1.tgz
+node --version
+npm --version
+```
+
+The coordinator records the JSON returned by each pack command together with the SHA256 output. Tarballs do not belong in either repository.
+
+### Install into a separate consumer
+
+Create or select a consumer directory that is not either source checkout. The two absolute archive paths must name the reviewed bytes whose digests were recorded.
+
+```sh
+cd <consumer-directory>
+npm init --yes
+npm pkg set private=true --json
+npm install --save-dev --ignore-scripts --no-audit --no-fund \
+  <artifact-directory>/picagear-0.1.0-next.0.tgz \
+  <artifact-directory>/decadra-0.4.1.tgz
+./node_modules/.bin/picagear --help
+```
+
+Use this consumer directory as `moduleRoot` in the local Decadra integration configuration. Keep Picagear factory data and the Decadra receiver directory at explicit, separate paths. See the [local integration contract](decadra-local-integration.md).
+
+## Evidence boundaries
+
+`npm run test:consumer` packs Picagear into a random scratch directory, checks the complete archive inventory, checks the packed manifest release metadata, installs it in a fresh private consumer with scripts disabled, checks the installed manifest release metadata, confirms the installed `LICENSE` matches the source, and runs the installed bin against a disposable Git repository and explicit data root in fake mode. It does not install from the npm registry, install the real Decadra archive, prove lifecycle system integration, call provider workers, use provider credentials, open a pull request, or authorize a live rehearsal. Successful runs remove only their validated scratch directory. Failed runs retain it and print its location for inspection.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "picagear",
+  "version": "0.1.0-next.0",
+  "description": "A local code factory: turn an epic into a weekly commitment, compile strict work orders, and run one task per pull request through Codex and Claude Code in isolated worktrees.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/picaworks/picagear.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "next"
+  },
+  "type": "module",
+  "bin": {
+    "picagear": "./dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "LICENSE",
+    "README.md",
+    "docs/local-installation.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --configLoader runner",
+    "test:watch": "vitest",
+    "test:consumer": "node scripts/consumer-smoke.mjs",
+    "check": "npm run format && npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "commander": "15.0.0",
+    "execa": "10.0.1",
+    "picocolors": "1.1.1",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "26.4.1",
+    "eslint": "10.10.0",
+    "prettier": "3.9.6",
+    "tsup": "8.5.1",
+    "tsx": "4.23.13",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  }
+}