woobe-cli 0.6.0 → 0.8.0

package/USAGE.md

@@ -407,3 +407,99 @@ fields and exact numeric values retain their meanings. A YAML API payload is
 not a portable Package: use `package import` for dependency-aware bundles.
 Manifests can also be written in YAML with the existing manifest schema.
 No project configuration file is required for request input or command help.
+
+## Optional local development registry
+
+`woobe init --root .woobe --context local` creates `.woobe-config` in the
+current directory. This YAML file identifies the registry and records resource
+UIDs, kinds, logical keys, aliases and paths relative to the artifact root.
+Keep it in Git. `.woobe/.state/` is private and ignored by Git.
+
+```yaml
+schema_version: 1
+registry_id: 71e7c0ee-ea31-48b9-a566-ad713b4b8407
+context: local
+root: .woobe
+defaults:
+  pull_environment: draft
+resources:
+  - uid: fae665bb-0817-4834-903e-3352815e9367
+    kind: Provider
+    key: openai-main
+    alias: openai-main
+    path: providers/openai-main
+```
+
+`woobe config show` displays this configuration. `woobe config check` validates
+registered descriptors and their dependency graph offline; it does not evaluate
+server permissions or execute mutations. `woobe resources list` lists the
+registry, while `woobe resources used-by provider "@openai-main"` shows direct
+and indirect local consumers, including embedding Models and Knowledge.
+
+Provider descriptors use `provider`, `credential_ref` and optional public
+`base_url`, `compatibility` and `provider_family` fields. Credential material
+belongs in the existing provider/auth workflow. Managed Model descriptors may
+use `provider_ref` to identify a registered Provider. Multiple Models can share
+a connection; two connections remain distinct registry resources.
+
+Development commands discover the nearest `.woobe-config` from the current
+folder, stopping at the Git repository boundary. `--project-config PATH` selects
+an explicit file; `--no-project-config` disables discovery. API requests,
+authentication, contexts, runtime calls and standalone packages do not load this
+file. Their operation is unaffected by a missing or malformed project config.
+
+## Pull, edit YAML, push Draft
+
+Managed development requires a Woobe server advertising `sync` and `registry`
+capabilities. The server validates the complete dependency graph and authorizes
+both the root and each reused artifact. Native UUIDs are retained for Agents and
+Networks; changed shared dependencies use explicit copy-on-write effects.
+
+```sh
+woobe init --context local
+woobe agent UUID pull --alias support
+woobe agent "@support" diff
+woobe agent "@support" validate
+woobe agent "@support" push
+woobe network UUID pull --alias helpdesk
+woobe network "@helpdesk" push
+```
+
+Edit the registered `agent.yaml`, `network.yaml` and dependency descriptors in
+between pull and push. Reference-first `sync` aliases `pull`, and `update` aliases
+`push`: `woobe agent UUID update --path ./.woobe/agents/support`. Canonical API
+`woobe agent update UUID --file patch.yaml` still accepts a raw request payload.
+Quote aliases in PowerShell (`"@support"`). UUID, exact remote name on the first
+pull, typed alias and registered folder are supported. Inside a linked folder,
+`woobe agent pull`/`push` can omit the reference.
+
+Pull defaults to Draft. `--env staging` and `--env production` select the current
+native snapshots; `--env release --version 1.2.0` selects an immutable release.
+Regardless of the pulled environment, push writes Draft. Publishing and
+activation remain explicit lifecycle operations. `--path` is an optional folder
+inside the configured artifact root; local resource identities stay in
+`.woobe-config`, destination UUIDs and base revisions stay in `.state/`.
+
+`diff` and `status` are offline and include dependency and declared support-file
+changes. `validate` checks the compiled portable schema offline; server semantic
+validation, credentials and authorization are checked during push. `--dry-run`
+never applies a push; its summary identifies local changes and dependencies.
+
+Pull performs a three-way merge against the last remote base. Independent edits
+merge; conflicting fields or support files leave all author files and state
+untouched. Push includes native revision evidence, so stale edits receive a
+conflict instead of overwriting another client. Pull again, resolve the listed
+paths, inspect diff and retry. Resetting or deleting local state is unnecessary.
+
+Networks preserve repeated nodes separately. An Agent Draft is editable, while
+fixed constituent snapshots remain under `snapshots/` with separate UIDs. Editing
+a frozen constituent is rejected; pull its standalone Draft to edit the Agent.
+A Network push does not activate constituent Agents as standalone Production.
+
+Local writes use a registry process lock and a durable transaction journal.
+Interrupted transactions recover on the next development command, and recovery
+refuses to overwrite a conflicting external edit. Push checkpoints pin the
+content, destination and principal. If acceptance is unknown, the next push
+looks up the same operation rather than sending another mutation. Keep `.state/`
+until the operation has been reconciled; it is intentionally excluded from Git
+and from compiled packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "woobe-cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Woobe CLI for the public control plane and runtime",
   "license": "UNLICENSED",
   "repository": {