@agimon-ai/po-config 0.0.0-alpha.83 → 0.0.0-alpha.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/po-config",
-  "version": "0.0.0-alpha.83",
+  "version": "0.0.0-alpha.85",
   "description": "Typed configuration loading, validation, and host services for composing Po sessions.",
   "keywords": [
     "agent-configuration",
@@ -139,14 +139,14 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@agimon-ai/po-core": "0.0.0-alpha.83",
-    "@agimon-ai/po-web-components": "0.0.0-alpha.83",
+    "@agimon-ai/po-core": "0.0.0-alpha.85",
+    "@agimon-ai/po-web-components": "0.0.0-alpha.85",
     "@deepseek-ai/cordis": "4.0.5",
     "typebox": "1.4.2",
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@agimon-ai/po-build": "0.0.0-alpha.83",
+    "@agimon-ai/po-build": "0.0.0-alpha.85",
     "@earendil-works/pi-coding-agent": "1.4.0",
     "@modelcontextprotocol/ext-apps": "2.0.3",
     "@modelcontextprotocol/server": "2.3.1",

package/src/prompts/help-how-to-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: help-how-to-config
-description: Configure Po runtime settings, workspace declarations, source precedence, and typed session configuration. Use for config.yaml, workspaces.yaml, the po/config or po/workspace-registry Cordis services, immutable context snapshots, or shared selection transition state. Do not use for defining modes.yaml, domains.yaml, or profiles.yaml.
+description: Configure Po runtime settings, workspace declarations and free-form metadata, source precedence, and typed session configuration. Use for config.yaml, workspaces.yaml, plugin metadata lookup through po/workspace-registry, workspace-scoped Cordis services, immutable context snapshots, or shared selection transition state. Do not use for defining modes.yaml, domains.yaml, or profiles.yaml.
 ---
 
 # Author Po runtime configuration
@@ -23,12 +23,25 @@ Configure runtime policy in `config.yaml`, declare workspaces in the repository'
 
 Use the package-owned Major Mode, Domain, or Profile Help skill when the task is to define an axis in `modes.yaml`, `domains.yaml`, or `profiles.yaml`.
 
-For workspaces, read the repository's `.po/workspaces.yaml` first. Its presence overrides the old
-`config.yaml` list, including an empty list; malformed new files are errors. Keep aliases unique
-within the file and paths canonically equal to the repository root in this version. Metadata is a
-free-form JSON object, checked and interpreted by each plugin. Never store credentials there.
-Use the injected `po/workspace-registry` instead of parsing files in plugins. Declaration names
-carry identity; changing one unlinks metadata from an already-created workspace. Core does not
-read `products.yaml` or enforce a plugin's scope.
+## Workspaces, metadata and services
+
+Read the repository's `.po/workspaces.yaml` first. Its presence overrides the old `config.yaml`
+list, including an empty list; malformed new files are errors. Keep aliases unique within the
+file and paths canonically equal to the repository root in this version. Declaration names
+carry identity; changing one unlinks metadata from an already-created workspace.
+
+Metadata is a free-form JSON object for other plugins to leverage, not a product-specific
+schema. Flat keys and plugin-namespaced blocks are both valid. Each consuming plugin validates
+and interprets the fields it uses. Core does not read `products.yaml` or enforce a plugin's
+scope. Never store credentials in metadata.
+
+Inject `po/workspace-registry` through Cordis instead of parsing files in plugins. Resolve the
+current `host.context.workspaceId` and read the returned workspace's metadata. Handle `missing`
+and `ambiguous` results explicitly; a shared root path does not identify same-root siblings.
+
+Registry lookup and workspace-scoped services are separate mechanisms. A plugin provides a
+workspace-scoped service through `po/server-scope`; other plugins in that workspace and its
+sessions consume it through normal Cordis injection. The registry exposes detached identity
+and metadata records, not another workspace's Cordis context or service instances.
 
 Read [references/config-contract.md](references/config-contract.md) for the runtime and workspace schemas, source merge rules, immutable context, and transition contract.

package/src/prompts/help-how-to-config/references/config-contract.md

@@ -70,6 +70,7 @@ workspaces:
     alias: product
     instructions: Focus on this product.
     metadata:
+      team: operations
       '@example/plugin': { projectId: 'product-id' }
 ```
 
@@ -81,9 +82,12 @@ strings preserved verbatim. Aliases are optional non-empty strings, unique withi
 canonically equal to that root (including equivalent symlinks). Subfolder and cross-repository
 paths fail explicitly. Multiple declarations share the root but have separate workspace ids.
 
-Metadata is a free-form JSON object. Plugin namespacing is conventional, not required. Core does
-not read `products.yaml`, validate plugin-specific blocks, select credentials or enforce tool
-scope. Each plugin decides its own policy. Never put credentials in metadata.
+Metadata is a free-form JSON object for other plugins to leverage, not a product-specific schema.
+Flat keys and plugin-namespaced blocks are both valid; namespacing is conventional, not required.
+Core validates JSON compatibility, but does not read `products.yaml`, validate plugin-specific
+blocks, select credentials or enforce tool scope. Each consuming plugin validates and interprets
+the fields it uses and decides whether they supply defaults or enforced policy. Never put
+credentials in metadata.
 
 An existing new document replaces the entire legacy list, including an empty list. Invalid or
 blank new documents fail instead of falling back. When absent, the repository `config.yaml`
@@ -97,10 +101,39 @@ workspaces. Metadata and aliases are not copied into `workspaces.json`. Instruct
 existing first-creation copy behavior. Renaming a declaration breaks its association with an
 existing workspace; aliases are lookup labels, not identity keys.
 
-Plugins inject `po/workspace-registry` through Cordis, then resolve their current
-`host.context.workspaceId`. The read-only service returns detached records and distinguishes
-`found`, `missing` and `ambiguous`. Same-root siblings are ambiguous by path; cross-file alias
-collisions are also ambiguous. It never returns another workspace's Cordis services.
+#### Consuming metadata and workspace services
+
+Plugins inject `po/workspace-registry` through Cordis instead of reading the YAML themselves:
+
+```ts
+import { PO_WORKSPACE_REGISTRY_SERVICE, readPoWorkspaceRegistry } from '@agimon-ai/po-core/workspaceRegistry';
+
+context.inject([PO_WORKSPACE_REGISTRY_SERVICE], async (context) => {
+  const registry = readPoWorkspaceRegistry(context)!;
+  const result = await registry.resolve({ id: host.context.workspaceId });
+  if (result.status !== 'found') return; // This optional integration stays inactive without a unique workspace.
+  const metadata = result.workspace.metadata;
+  // Validate the fields this plugin consumes before applying its defaults or policy.
+});
+```
+
+`list()` returns detached workspace records. `resolve()` accepts exactly one selector: `{ id }`,
+`{ name }`, `{ path }` or `{ alias }`, and distinguishes `found`, `missing` and `ambiguous`.
+Use the current workspace id for session-local integrations. Same-root siblings are ambiguous
+by path; cross-file alias collisions are also ambiguous. Do not pick the first candidate.
+An optional integration may stay inactive when resolution is not `found`; a required integration
+must report the missing or ambiguous workspace instead of silently applying another workspace's policy.
+
+Workspace-scoped services are separate from this registry. Their provider declares a contract
+with `defineServiceContract(name, { scope: 'workspace' })` and binds it with
+`requirePoServerScope(context).provide(contract, service)` from `@agimon-ai/po-core/serverPlugin`.
+Other plugins in that workspace and its descendant sessions acquire the service through normal
+Cordis `context.inject([contract.name], ...)` and `context.get(contract.name)`. A global scope
+cannot see services provided below it, and sibling workspaces do not inherit one another's services.
+Plugins can combine the current workspace's metadata with its injected services. The registry
+itself is read-only inventory, not a cross-workspace service locator; it never returns another
+workspace's Cordis context or services.
+
 The current edge host exposes only its admitted tenant id/root with empty metadata, since edge
 admission does not yet associate a tenant id with a declaration key.