Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
e393793
feat(scope): add durable organization and bindings
PsiACE Sep 2, 2026
a1d0fb0
feat(migration): register existing runtime scopes
PsiACE Sep 2, 2026
99e4088
feat(artifact): publish exact revisions across scopes
PsiACE Sep 2, 2026
bbd4c4a
refactor(scope): replace project reporting with selections
PsiACE Sep 2, 2026
5cce29b
feat(integrations): resolve server-owned scopes
PsiACE Sep 2, 2026
14278d2
test(scope): verify selection and plugin contracts
PsiACE Sep 2, 2026
5d5b550
docs(scope): explain server-owned organization
PsiACE Sep 2, 2026
605701b
refactor(scope): remove legacy runtime migration
PsiACE Sep 2, 2026
d8a637d
fix(scope): retry bindings without savepoints
PsiACE Sep 2, 2026
325f20d
fix(scope): reject unregistered runtime partitions
PsiACE Sep 2, 2026
f45cc69
fix(scope): serialize hierarchy mutations
PsiACE Sep 2, 2026
056dd9e
fix(codex): guard operations by scope mode
PsiACE Sep 2, 2026
5e35afd
fix(publication): reject incomplete memory copies
PsiACE Sep 2, 2026
83f5235
chore: merge master into scope runtime
PsiACE Sep 2, 2026
3daf855
fix(ci): escape plugin shell variable safely
PsiACE Sep 2, 2026
74abed5
chore: merge latest master into scope runtime
PsiACE Sep 3, 2026
015dc00
chore: merge latest master into scope runtime
PsiACE Sep 3, 2026
befc32f
chore: merge latest master into scope runtime
PsiACE Sep 3, 2026
3a14f3a
fix(runtime): preserve referenced scope recall
PsiACE Sep 3, 2026
a7e5e7b
fix(publication): make delivery atomic
PsiACE Sep 3, 2026
94b388a
docs: use registered scope identifiers
PsiACE Sep 3, 2026
e02e10d
chore: merge latest master into scope runtime
PsiACE Sep 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: use registered scope identifiers
  • Loading branch information
PsiACE committed Sep 3, 2026
commit 94b388a1aeb4aee00fc92c1ae371915efc26bdd6
1 change: 0 additions & 1 deletion docs/en/docs/how-to/configure-pydantic-ai.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,6 @@ agent = Agent("openai:gpt-5.2", toolsets=[PowerContextToolset()])
```bash
export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000
export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token
export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example
```

| Variable | Default | Validation and behavior |
Expand Down
17 changes: 9 additions & 8 deletions docs/en/docs/how-to/create-and-export-skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ In another terminal:
powercontext capabilities
```

The output should report `Managed Skill generation: enabled`. Choose one provenance origin before generating:
The output should report `Managed Skill generation: enabled`. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned
by `create_scope`, then choose one provenance origin before generating:

| Origin | Use it when |
| --- | --- |
Expand All @@ -37,7 +38,7 @@ From an approved Experience:

```bash
powercontext skill generate \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--origin experience \
--artifact-ref experience/EXPERIENCE_ID@REVISION \
--reason "Turn the reviewed lesson into reusable instructions."
Expand All @@ -47,7 +48,7 @@ From exact Sources instead:

```bash
powercontext skill generate \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--origin source \
--source-ref content/SOURCE_ID \
--reason "Create a Skill from the approved operating procedure."
Expand All @@ -61,15 +62,15 @@ approve, install, export, or execute the proposal.
Inspect the returned Candidate:

```bash
powercontext candidate show --scope-id project:example CANDIDATE_ID
powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID
```

Check its name, discovery description, complete instructions, validation checks, and exact lineage. Then approve the
version you inspected:

```bash
powercontext candidate approve \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
CANDIDATE_ID
```
Expand All @@ -83,7 +84,7 @@ Use the Artifact ID and Revision from `result_artifact`:

```bash
powercontext skill show \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--revision 1 \
SKILL_ID
```
Expand All @@ -100,7 +101,7 @@ must contain at most 1,024 characters and no angle brackets. The destination dir
```bash
powercontext skill export \
--target codex \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--revision 1 \
--destination .agents/skills/backend-validation \
SKILL_ID
Expand All @@ -125,7 +126,7 @@ Use the `usage` origin with the exact current Skill Revision and Sources that re

```bash
powercontext skill generate \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--origin usage \
--target skill/SKILL_ID@REVISION \
--source-ref content/USAGE_SOURCE_ID \
Expand Down
13 changes: 7 additions & 6 deletions docs/en/docs/how-to/create-and-review-experience.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,16 @@ powercontext capabilities
```

The output should report `Experience generation: enabled`. You also need at least one exact Source or Artifact
reference in the target scope. Provider credentials come from the selected inference provider.
reference in the target scope. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`. Provider
credentials come from the selected inference provider.

## 1. Generate a Candidate

Pass the exact evidence that supports the proposed Experience:

```bash
powercontext experience generate \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--source-ref content/SOURCE_ID \
--reason "Extract a reusable lesson from the completed task."
```
Expand All @@ -49,14 +50,14 @@ Generation does not approve or recall the proposal.
For a pending result, copy its `candidate_id` and `version`, then inspect it:

```bash
powercontext candidate show --scope-id project:example CANDIDATE_ID
powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID
```

Check all four Experience fields and their exact evidence. Approve only the version you inspected:

```bash
powercontext candidate approve \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
CANDIDATE_ID
```
Expand All @@ -69,7 +70,7 @@ follow [Review Candidates](review-candidates.md).
Read the Candidate again and record `result_artifact`:

```bash
powercontext candidate show --scope-id project:example CANDIDATE_ID
powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID
```

The approved current head is now eligible for same-scope `PreparedContext` recall. Eligibility does not guarantee
Expand All @@ -82,7 +83,7 @@ Generate a replacement against the exact current Revision and cite the evidence

```bash
powercontext experience generate \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--target experience/EXPERIENCE_ID@REVISION \
--source-ref content/NEW_SOURCE_ID \
--reason "Update the lesson with the verified follow-up result."
Expand Down
8 changes: 5 additions & 3 deletions docs/en/docs/how-to/ingest-text-files-with-opendal.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ uv tool install --python 3.12 --with-editable ".[client]" ./integrations/opendal

Choose a stable `source_namespace` that distinguishes storage authorities. Do not put credentials in the namespace,
Source payload, or checkpoint. If Server authentication is enabled, provide its bearer token through the
`POWERCONTEXT_TOKEN` environment variable.
`POWERCONTEXT_TOKEN` environment variable. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`.

## Run a binding

Expand All @@ -33,7 +33,7 @@ the `scope_id` determines which Scope owns accepted Sources:
```bash
powercontext-connector-opendal \
--base-url http://127.0.0.1:8765 \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--binding-id project-docs \
--service fs \
--storage-option root=/absolute/path/to/project \
Expand All @@ -53,6 +53,8 @@ have durable receipts. Use cron, a Kubernetes Job, or another external scheduler
Use the generic remote lifecycle when a deployment needs custom supervision or schedules multiple bindings:

```python
import os

from powercontext.client import PowerContextClient, RemoteConnectorWorker
from powercontext.sources import ConnectorBinding, SourceDefinitionRegistry
from powercontext_connector_opendal import (
Expand All @@ -67,7 +69,7 @@ connector = OpenDALTextFileConnector.from_service(
storage_options={"root": "/absolute/path/to/project"},
)
binding = ConnectorBinding(
scope_id="project:example",
scope_id=os.environ["POWERCONTEXT_SCOPE_ID"],
binding_id="project-docs",
connector_name=connector.name,
connector_version=connector.version,
Expand Down
26 changes: 13 additions & 13 deletions docs/en/docs/how-to/review-candidates.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,20 @@ Start the Server and confirm that it is ready:
powercontext ready
```

You need the `scope_id` that contains the Candidate. This guide starts after an Experience or Skill operation has
created a pending Candidate.
Set `POWERCONTEXT_SCOPE_ID` to the existing Scope ID that contains the Candidate. This guide starts after an
Experience or Skill operation has created a pending Candidate.

## 1. List pending Candidates

```bash
powercontext candidate list --scope-id project:example
powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID"
```

The default Review Inbox contains only `pending` Candidate heads. Filter it by family when needed:

```bash
powercontext candidate list --scope-id project:example --family experience
powercontext candidate list --scope-id project:example --family skill
powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family experience
powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family skill
```

The response contains each `candidate_id` and current `version`. If it returns `next_cursor`, pass that value through
Expand All @@ -38,7 +38,7 @@ The response contains each `candidate_id` and current `version`. If it returns `
## 2. Inspect one Candidate

```bash
powercontext candidate show --scope-id project:example CANDIDATE_ID
powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID
```

Before deciding, inspect:
Expand All @@ -60,7 +60,7 @@ Use the `version` you inspected as `--expected-version`.

```bash
powercontext candidate approve \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
CANDIDATE_ID
```
Expand All @@ -72,7 +72,7 @@ Candidate approved in one transaction. The Candidate is then terminal.

```bash
powercontext candidate reject \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
--reason "The evidence does not support the proposed lesson." \
CANDIDATE_ID
Expand All @@ -88,7 +88,7 @@ version:

```bash
powercontext candidate revise experience \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
--situation "Only one storage backend was tested." \
--action "Run the same acceptance scenario on both backends." \
Expand All @@ -107,7 +107,7 @@ Repeat `--validation` for each check:

```bash
powercontext candidate revise skill \
--scope-id project:example \
--scope-id "$POWERCONTEXT_SCOPE_ID" \
--expected-version 1 \
--name backend-validation \
--description "Validate storage backends consistently." \
Expand All @@ -126,15 +126,15 @@ automatically.
Read the Candidate again:

```bash
powercontext candidate show --scope-id project:example CANDIDATE_ID
powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID
```

For an approved Candidate, record the exact `result_artifact`. For a rejected Candidate, confirm `decision_reason`.
The default Inbox no longer lists either terminal state; audit them explicitly when needed:

```bash
powercontext candidate list --scope-id project:example --status approved
powercontext candidate list --scope-id project:example --status rejected
powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status approved
powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status rejected
```

If a write reports that the Candidate version is stale, show the Candidate again and review the new version. Do not
Expand Down
7 changes: 4 additions & 3 deletions docs/en/docs/how-to/trace-with-phoenix.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,18 +49,19 @@ authentication. Set the provider credentials your generation model needs; PowerC

## Trigger one inference request

Capture a Source, then convert it into Memory:
Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`, capture a Source, then convert it into
Memory:

```bash
curl -X POST http://localhost:8000/v1/sources/content \
-H 'content-type: application/json' \
-d '{"scope_id":"project:demo","source_id":"task-1","content":"I always book aisle seats."}'
-d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\",\"source_id\":\"task-1\",\"content\":\"I always book aisle seats.\"}"
```

```bash
curl -X POST http://localhost:8000/v1/memory/flush \
-H 'content-type: application/json' \
-d '{"scope_id":"project:demo"}'
-d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\"}"
```

Memory extraction runs during the flush, not during capture.
Expand Down
24 changes: 12 additions & 12 deletions docs/en/docs/reference/http-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ curl --fail \

## Store and search one Memory

Choose a stable `scope_id` for the project or tenant. Reuse it across sessions; a session ID is not a durable project
identity.
Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`. Reuse that Scope across sessions; a Session
ID is not a durable project identity.

Store one already-curated Memory entry:

Expand All @@ -66,11 +66,11 @@ curl --fail \
--request POST \
--header 'Content-Type: application/json' \
--header "$POWERCONTEXT_AUTH_HEADER" \
--data '{
"scope_id": "project:example",
"kind": "decision",
"text": "Keep the public API asynchronous."
}' \
--data "{
\"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\",
\"kind\": \"decision\",
\"text\": \"Keep the public API asynchronous.\"
}" \
"$POWERCONTEXT_URL/v1/memory/remember"
```

Expand All @@ -84,11 +84,11 @@ curl --fail \
--request POST \
--header 'Content-Type: application/json' \
--header "$POWERCONTEXT_AUTH_HEADER" \
--data '{
"scope_id": "project:example",
"query": "public API",
"limit": 5
}' \
--data "{
\"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\",
\"query\": \"public API\",
\"limit\": 5
}" \
"$POWERCONTEXT_URL/v1/memory/search"
```

Expand Down
18 changes: 10 additions & 8 deletions docs/en/docs/reference/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,8 @@ boundary flushing fail open; explicit durable writes require interactive confirm

## CLI

Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope` before running scoped content commands.

```text
powercontext setup <host> --source oceanbase/powercontext --ref master
powercontext setup select --host codex --host dsh --source oceanbase/powercontext --ref master
Expand All @@ -141,16 +143,16 @@ powercontext server run
powercontext server run --env-file .env
powercontext ready
powercontext capabilities
powercontext experience generate --scope-id project:example --source-ref content/SOURCE_ID
powercontext skill generate --scope-id project:example --origin experience \
powercontext experience generate --scope-id "$POWERCONTEXT_SCOPE_ID" --source-ref content/SOURCE_ID
powercontext skill generate --scope-id "$POWERCONTEXT_SCOPE_ID" --origin experience \
--artifact-ref experience/EXPERIENCE_ID@REVISION
powercontext skill show --scope-id project:example --revision 1 SKILL_ID
powercontext skill export --target codex --scope-id project:example --revision 1 \
powercontext skill show --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 SKILL_ID
powercontext skill export --target codex --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 \
--destination .agents/skills/example-skill SKILL_ID
powercontext external-skill scan --scope-id project:example
powercontext external-skill list --scope-id project:example
powercontext external-skill resolve --scope-id project:example --fingerprint SHA256 EXTERNAL_SKILL_ID
powercontext external-skill import --scope-id project:example --fingerprint SHA256 \
powercontext external-skill scan --scope-id "$POWERCONTEXT_SCOPE_ID"
powercontext external-skill list --scope-id "$POWERCONTEXT_SCOPE_ID"
powercontext external-skill resolve --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 EXTERNAL_SKILL_ID
powercontext external-skill import --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 \
--mode import EXTERNAL_SKILL_ID
```

Expand Down
12 changes: 9 additions & 3 deletions docs/en/docs/tutorials/api-quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,17 @@ Experience and Skill proposals.

## 2. Choose the application boundary

Set a stable scope for one project or tenant:
Create a stable Scope for one project or tenant and keep the returned Server-owned ID:

```bash
export POWERCONTEXT_URL=http://127.0.0.1:8000
export POWERCONTEXT_SCOPE=project:billing-assistant
export POWERCONTEXT_SCOPE="$(
curl --fail --silent --show-error \
--header 'Content-Type: application/json' \
--data '{"title":"Billing assistant","summary":"Billing application context","idempotency_key":"billing-assistant"}' \
"$POWERCONTEXT_URL/v1/scopes" \
| python -c 'import json, sys; print(json.load(sys.stdin)["scope_id"])'
)"
```

Your trusted application or Gateway must choose and authorize `scope_id`. It is a data partition key, not an access
Expand Down Expand Up @@ -76,7 +82,7 @@ from urllib.request import Request, urlopen


BASE_URL = os.environ.get("POWERCONTEXT_URL", "http://127.0.0.1:8000").rstrip("/")
SCOPE_ID = os.environ.get("POWERCONTEXT_SCOPE", "project:billing-assistant")
SCOPE_ID = os.environ["POWERCONTEXT_SCOPE"]
TOKEN = os.environ.get("POWERCONTEXT_TOKEN")


Expand Down
1 change: 0 additions & 1 deletion docs/zh/docs/how-to/configure-pydantic-ai.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,6 @@ agent = Agent("openai:gpt-5.2", toolsets=[PowerContextToolset()])
```bash
export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000
export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token
export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example
```

| 变量 | 默认值 | 校验与行为 |
Expand Down
Loading
Loading