Skip to content

docs(onboarding): document capabilities, triggers, and Hook trust for… - #2047

Merged
hidb4ai merged 2 commits into
oceanbase:masterfrom
Lkx-JY:codex/issue-1713-onboarding
Oct 19, 2026
Merged

hidb4ai merged 2 commits into
oceanbase:masterfrom
Lkx-JY:codex/issue-1713-onboarding

Conversation

@Lkx-JY

@Lkx-JY Lkx-JY commented Oct 17, 2026

Copy link
Copy Markdown
Contributor

Which issue or RFC does this PR close?

Closes #1713.

Builds on #2003 (merged).

Rationale for this change

#2003 improved the English, Chinese, and Japanese READMEs: it clarified what PowerContext is, explained Scope and the main artifacts, added Dashboard examples with synthetic records, and made benchmark results readable as text. It also documented boundaries such as immutable Revisions, review, and explicit Skill export. That PR explicitly left the installation-path Skills guidance in #1713 unresolved.

This PR addresses the remaining onboarding gaps. Users following README and Quick Start need to know which capabilities they can use, how to request them, which require Server models or policies, and how to recognize successful results. They also need the first-session Hook trust step before checking automatic capture and recall. MCP connectivity alone does not establish that either has run.

Area What #2003 covered What this PR adds
Capability guidance Product concepts and the main artifact roles in README A bilingual guide covering all seven current Artifact families, Source, and Tag, with triggers or supported entry points, prerequisites, results, and workflow links
First successful use Product examples and README usability improvements Explicit Basic/Full acceptance paths and first-session Hook trust, disabled-hook behavior, and recovery guidance
Managed Skills Approval does not install or execute a Skill; export is explicit A clear distinction between bundled routing guidance and managed Skills, linked to exact-revision export and host discovery
Documentation consistency README explanations of revision, review, and export boundaries Matching Handoff authorization across related host guides and the tutorial, plus current family, lifecycle, and Tag descriptions in Core Concepts and architecture

What changes are included in this PR?

  • Add first-session Hook trust checks, the impact of disabled hooks, and recovery guidance to the onboarding path. Keep detailed instructions in the Codex guide and link them from all three READMEs.
  • Separate Basic and Full memory acceptance paths, with concrete prompts and observable results.
  • Add an English/Chinese guide to seven Artifact families, Source, and Tag, including operation entry points, model/policy requirements, and workflow links. Distinguish MCP operations from HTTP/CLI management workflows.
  • Distinguish the bundled routing Skill from managed Skills, and explain review, exact-revision export, host discovery, and execution authority.
  • Align Handoff authorization across the Codex plugin README, Codex/Claude Code/WorkBuddy integration guides, the bilingual Codex tutorial, and the capability matrix. Ordinary transfer returns a temporary carrier; explicit durable intent permits commit; a read-only preview makes no writes. The tutorial explicitly requests a committed milestone before its receiving-session step. This documents the existing contract in scripts/guidance_templates/base/references/work-handoff.md.j2 and the generated host Skills; it does not change runtime authorization.
  • Align Core Concepts and the architecture guide with the seven current Artifact families, Topic Memory generic writes, and Tag coverage. Core Concepts distinguishes Atomic Memory's readable states from the forgotten lifecycle request and links legacy memory compatibility to the migration guide. Clarify that downloading a Skill package alone does not establish installation, and update links to the revised Quick Start section.

Are there any user-facing changes?

Yes. The documentation now guides users through first-session Hook trust and mode-appropriate checks, then into supported workflows. No runtime APIs, persistence formats, or dependencies change.

How was this change tested?

  • UV_CACHE_DIR=/tmp/pc-1713-uv-cache uv run --no-sync pytest tests/test_release_version.py tests/test_full_capability_docs.py -q — 14 passed.
  • UV_CACHE_DIR=/tmp/pc-1713-uv-cache uv run --no-sync python scripts/release_version.py --check — passed.
  • make docs-test — passed: website lint, 13 website tests, 2 link-validation tests, production build, and verification of 940 public pages and their internal links.
  • git diff --check — passed.

Capability names and entry points were checked against the MCP catalog, Artifact/Tag types, Atomic Memory state/lifecycle contracts, the base Handoff guidance template, and generated Codex/Claude Code/WorkBuddy Skills. Native Codex trust prompts, host Handoff transfers, live model extraction, and host Skill discovery were not executed; passing documentation checks does not establish those host workflows.

AI usage statement

Implemented and verified with OpenAI Codex. AI assistance was used for source tracing, implementation, regression-test design, documentation, and validation; the resulting changes were reviewed locally.

@AlexStocks AlexStocks added the 1.4.0 v1.4.0 release tracking label Oct 17, 2026

@hireview001 hireview001 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Resolve merge conflicts with the target branch.

@hireview001 hireview001 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@hidb4ai hidb4ai left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@hidb4ai
hidb4ai merged commit 04b85da into oceanbase:master Oct 19, 2026
36 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1.4.0 v1.4.0 release tracking

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: One-line install lacks Skills guidance; README/Quick Start path has poor usability

4 participants