From b68135926bffa1240c35ad75a4d3a47c4a9d2e2a Mon Sep 17 00:00:00 2001
From: Eric Nordelo <eric.nordelo39@gmail.com>
Date: Wed, 29 Apr 2026 14:16:09 +0200
Subject: [PATCH 1/5] feat: add docs-sync skill

---
 skills/docs-sync/SKILL.md                     | 153 +++++++
 .../config/libraries/contracts-sui.yml        |  74 ++++
 skills/docs-sync/process.md                   | 331 +++++++++++++++
 skills/docs-sync/references/checks/README.md  |  31 ++
 .../references/checks/check_code_snippets.md  |  78 ++++
 .../references/checks/check_links.md          |  74 ++++
 .../checks/check_nav_consistency.md           |  77 ++++
 .../references/checks/compare_public_api.md   |  98 +++++
 .../references/checks/detect_missing_pages.md |  75 ++++
 .../references/checks/extract_public_api.md   | 123 ++++++
 .../checks/find_stale_identifiers.md          |  84 ++++
 .../reports/docs-sync-report-template.md      |  52 +++
 .../references/rules/api-reference-rules.md   | 238 +++++++++++
 .../references/rules/change-classification.md | 388 ++++++++++++++++++
 .../references/rules/config-rules.md          |  97 +++++
 .../references/rules/diataxis-rules.md        | 178 ++++++++
 .../references/rules/doc-update-matrix.md     | 277 +++++++++++++
 .../references/rules/docs-pr-checklist.md     | 139 +++++++
 .../templates/api-reference-template.md       | 186 +++++++++
 .../templates/explanation-template.md         | 127 ++++++
 .../references/templates/guide-template.md    | 147 +++++++
 .../references/templates/tutorial-template.md | 145 +++++++
 22 files changed, 3172 insertions(+)
 create mode 100644 skills/docs-sync/SKILL.md
 create mode 100644 skills/docs-sync/config/libraries/contracts-sui.yml
 create mode 100644 skills/docs-sync/process.md
 create mode 100644 skills/docs-sync/references/checks/README.md
 create mode 100644 skills/docs-sync/references/checks/check_code_snippets.md
 create mode 100644 skills/docs-sync/references/checks/check_links.md
 create mode 100644 skills/docs-sync/references/checks/check_nav_consistency.md
 create mode 100644 skills/docs-sync/references/checks/compare_public_api.md
 create mode 100644 skills/docs-sync/references/checks/detect_missing_pages.md
 create mode 100644 skills/docs-sync/references/checks/extract_public_api.md
 create mode 100644 skills/docs-sync/references/checks/find_stale_identifiers.md
 create mode 100644 skills/docs-sync/references/reports/docs-sync-report-template.md
 create mode 100644 skills/docs-sync/references/rules/api-reference-rules.md
 create mode 100644 skills/docs-sync/references/rules/change-classification.md
 create mode 100644 skills/docs-sync/references/rules/config-rules.md
 create mode 100644 skills/docs-sync/references/rules/diataxis-rules.md
 create mode 100644 skills/docs-sync/references/rules/doc-update-matrix.md
 create mode 100644 skills/docs-sync/references/rules/docs-pr-checklist.md
 create mode 100644 skills/docs-sync/references/templates/api-reference-template.md
 create mode 100644 skills/docs-sync/references/templates/explanation-template.md
 create mode 100644 skills/docs-sync/references/templates/guide-template.md
 create mode 100644 skills/docs-sync/references/templates/tutorial-template.md

diff --git a/skills/docs-sync/SKILL.md b/skills/docs-sync/SKILL.md
new file mode 100644
index 00000000..0110e452
--- /dev/null
+++ b/skills/docs-sync/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: docs-sync
+description: Update the centralized OpenZeppelin docs repo after a smart contracts library changes. Use after a contracts release, a merged PR in a contracts library, or any time you need to bring a docs slice (library + version) back in line with the contracts repo. The skill takes two contract commits (BASE_COMMIT, HEAD_COMMIT) as the source of truth and produces docs edits that follow the Diátaxis framework. Trigger on phrases like "sync docs for contracts-sui", "update docs after the contracts PR", "regenerate API reference for v1.x", "docs-sync".
+---
+
+# docs-sync
+
+Use this skill when the contracts library has changed and the centralized
+docs repo needs to be brought back in sync. The skill lives **inside the
+docs repo**; the contracts repo is supplied at runtime.
+
+## When to use
+
+- A contracts library has merged a PR or cut a release and the docs need
+  updating.
+- The user names a docs slice and two commits in the contracts repo.
+- The user asks to "sync docs", "update API reference for `<LIBRARY_ID>`",
+  or "document the changes between commit A and commit B".
+
+Do **not** trigger this skill for:
+
+- Pure docs cleanup unrelated to contracts changes (use a regular edit).
+- Changes that have not yet landed in a commit on the contracts repo.
+
+## Required runtime inputs
+
+Collect these before editing:
+
+- `<MODE>`: `interactive` or `automatic`.
+- `<CONTRACTS_REPO_PATH>`: local path to the contracts repo (runtime).
+- `<DOCS_REPO_PATH>`: local path to this docs repo (runtime).
+- `<BASE_COMMIT>`: contracts commit immediately **before** the change set.
+- `<HEAD_COMMIT>`: contracts commit at the **tip** of the change set.
+- `<LIBRARY_ID>`: docs slice id (e.g. `contracts-sui`).
+- `<DOCS_VERSION>`: docs version (e.g. `1.x`).
+- `<RELEASE_VERSION>`: human-facing release tag (e.g. `v1.1.0`).
+- `<DOCS_UPDATE_SCOPE>`: `full`, `api-only`, `guides-only`, or
+  `targeted:<paths>`. Default: `full`.
+
+Optional:
+
+- `<TARGET_AUDIENCE>`
+- `<DOCS_TONE>`
+
+## Source-of-truth constraint
+
+The contracts diff is computed by the agent itself, from two commits:
+
+```
+git -C <CONTRACTS_REPO_PATH> diff <BASE_COMMIT>..<HEAD_COMMIT>
+```
+
+The skill must **not** accept any of the following as the primary source
+of truth:
+
+- Raw pasted diffs.
+- Patch files.
+- Uncommitted local changes.
+- PR descriptions or commit messages.
+- Informal change summaries.
+
+## Mode selection
+
+1. If the caller passed `<MODE>`, use it.
+2. Otherwise read `automation.default_mode` from config
+   (`skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`).
+3. Otherwise default to `interactive`.
+
+- **interactive**: summarize and classify first. Ask only questions that
+  change scope, examples, release notes, audience, or security framing.
+  API reference edits may proceed deterministically; broad guide,
+  tutorial, or explanation rewrites need confirmation.
+- **automatic**: ask no questions. Infer from config and sibling pages,
+  apply all required matrix updates within scope, and record assumptions.
+  If a required decision cannot be inferred safely, stop or leave a
+  `needs-human-review` finding instead of fabricating content.
+
+## Scope selection
+
+- `full`: apply the full matrix.
+- `api-only`: update API reference, source links, stale identifiers in
+  API pages, and API navigation only. Report skipped guide/tutorial/
+  explanation/example/release-note work as out of scope.
+- `guides-only`: update guides, tutorials, explanations, and snippets.
+  Still inspect the API diff so stale prose can be found, but do not
+  regenerate reference pages.
+- `targeted:<paths>`: edit only the listed docs paths plus required
+  navigation changes for those paths. Report every matrix-required
+  update outside the target set as skipped.
+
+## Config memory
+
+Always load:
+
+```
+skills/docs-sync/config/libraries/<LIBRARY_ID>.yml
+```
+
+This file is committed to the docs repo and is the canonical source of
+docs slice paths, navigation system, examples style, security rules, and
+automation defaults. Read `references/rules/config-rules.md` only when
+config is missing, malformed, or needs a durable convention update.
+
+All `docs.*` paths in config are **relative to `<DOCS_REPO_PATH>`**. Never
+hard-code absolute filesystem paths in config, prompts, reports, or
+generated docs.
+
+## Reference Files
+
+Read only what the run needs:
+
+1. `process.md` — the deterministic end-to-end workflow.
+2. `references/rules/change-classification.md` — how to classify each
+   contract change.
+3. `references/rules/doc-update-matrix.md` — what docs each change type
+   forces.
+4. `references/rules/api-reference-rules.md` — required for API
+   reference updates.
+5. `references/rules/diataxis-rules.md` — required when creating or reshaping tutorial,
+   guide, explanation, or reference content.
+6. Templates under `references/templates/` — only when creating new
+   pages or replacing a broken structure.
+7. `references/rules/docs-pr-checklist.md` and
+   `references/reports/docs-sync-report-template.md` — final validation
+   and summary.
+
+Use the validation specs under `references/checks/` as check definitions. They are
+not executable scripts unless later replaced with real tooling.
+
+## Scope of edits
+
+Edit only:
+
+- Files inside the resolved docs slice
+  (`docs.library_root` and `docs.version_root` from config, recursively).
+- The matching navigation config (`docs.nav_config_path`).
+- Shared example files **only if** the matrix says they must change.
+
+Do **not**:
+
+- Touch other docs slices in the centralized repo.
+- Create or edit `meta.json` files. The docs repo uses centralized
+  navigation under `src/navigation/` — see the local conventions file
+  at `docs.local_conventions_path` for slice-specific rules.
+- Modify source/doc comments in the contracts repo unless
+  `automation.allow_source_comment_edits: true` **and** the user asked.
+
+## End of run
+
+Run through `references/rules/docs-pr-checklist.md` before claiming the
+run is done. End with a compact docs-sync report following
+`references/reports/docs-sync-report-template.md`. Do not create a
+report file unless the user asks for one.
diff --git a/skills/docs-sync/config/libraries/contracts-sui.yml b/skills/docs-sync/config/libraries/contracts-sui.yml
new file mode 100644
index 00000000..bd12f44f
--- /dev/null
+++ b/skills/docs-sync/config/libraries/contracts-sui.yml
@@ -0,0 +1,74 @@
+# docs-sync configuration for the OpenZeppelin Contracts for Sui docs slice.
+#
+# All paths are RELATIVE to <DOCS_REPO_PATH>. Local filesystem paths
+# must NOT be added to this file; they are runtime inputs to the agent.
+
+library:
+  id: "contracts-sui"
+  language: "MOVE_SUI"
+
+docs:
+  content_root: "content"
+  library_root: "content/contracts-sui"
+  version: "1.x"
+  version_root: "content/contracts-sui/1.x"
+  api_reference_path: "content/contracts-sui/1.x/api"
+  product_index_path: "content/contracts-sui/index.mdx"
+  version_index_path: "content/contracts-sui/1.x/index.mdx"
+  local_conventions_path: "content/contracts-sui/AGENTS.md"
+  nav_config_path: "src/navigation/sui/current.json"
+  tone: "clear, precise, security-conscious"
+  target_audience: "smart contract developers integrating OpenZeppelin libraries"
+
+navigation:
+  system: "central-json"
+  forbid_meta_json: true
+  # Categories the agent must keep in sync inside nav_config_path. New modules
+  # must appear under both "Packages" and "API Reference" folders.
+  required_folders:
+    - "Learn"
+    - "Packages"
+    - "API Reference"
+
+examples:
+  compile_command: ""
+  snippet_validation: "syntax"
+  # Where in-repo example projects live, if any. Empty when examples are
+  # only embedded as code fences in MDX files.
+  examples_root: ""
+
+security:
+  warning_style: "explicit warning callouts for security-sensitive behavior"
+  require_security_sections_for:
+    - access_control
+    - ownership
+    - authorization
+    - asset_transfer
+    - upgradeability
+    - cryptography
+    - signature_verification
+
+release:
+  # GitHub source URL used by APIGithubLinkHeader and similar components.
+  # Pinned per release tag at runtime by the agent.
+  source_repo_url: "https://github.com/OpenZeppelin/contracts-sui"
+
+automation:
+  default_mode: "interactive"
+  allow_source_comment_edits: false
+  fail_on_unresolved_placeholders: true
+
+# API Reference layout assumptions specific to this slice. Each Move package
+# is documented as a single MDX file under api_reference_path, named after
+# the package (kebab-case if multi-word). Modules inside that package render
+# as <APIItem>-style sections. See content/contracts-sui/AGENTS.md for the
+# canonical entry order (description, then Aborts, then Emits).
+api_reference_layout:
+  page_per: "package"
+  module_section_component: "APIItem"
+  github_link_component: "APIGithubLinkHeader"
+  entry_order:
+    - "description"
+    - "aborts"
+    - "emits"
+    - "callouts"
diff --git a/skills/docs-sync/process.md b/skills/docs-sync/process.md
new file mode 100644
index 00000000..ca9e37c7
--- /dev/null
+++ b/skills/docs-sync/process.md
@@ -0,0 +1,331 @@
+# docs-sync process
+
+A deterministic, top-to-bottom workflow. Steps run in order. Do not
+reorder. If a step fails, stop and surface the failure rather than
+skipping ahead.
+
+All paths in this document are relative to `<DOCS_REPO_PATH>` unless
+explicitly prefixed with `<CONTRACTS_REPO_PATH>`.
+
+---
+
+## Step 1 — Select mode
+
+1. If the caller passed `<MODE>`, use it.
+2. Otherwise read `automation.default_mode` from the config file
+   (Step 2).
+3. Otherwise default to `interactive`.
+
+Mode behavior:
+
+- `interactive`: summarize and classify before broad edits. Ask only
+  questions whose answers change scope, examples, release notes,
+  audience, or security framing. API reference edits can proceed
+  deterministically; broad guide/tutorial/explanation rewrites need
+  confirmation.
+- `automatic`: ask no questions. Infer from config and sibling pages.
+  Record assumptions. If a required decision cannot be inferred safely,
+  stop or record `needs-human-review` rather than inventing context.
+
+## Step 2 — Load config memory
+
+1. Resolve `<CONFIG_PATH>`. Default:
+   `skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`.
+2. If the file does not exist, **stop**. Do not fabricate a config; ask
+   the user (interactive) or fail with a clear message (automatic).
+3. Parse the file as YAML.
+4. Read `library.id`, `library.language`, `docs.*`, `navigation.*`,
+   `examples.*`, `security.*`, `release.*`, `automation.*`.
+5. Treat all `docs.*` paths as relative to `<DOCS_REPO_PATH>`.
+6. Apply optional overrides from runtime: `<TARGET_AUDIENCE>` overrides
+   `docs.target_audience`; `<DOCS_TONE>` overrides `docs.tone`.
+
+## Step 3 — Resolve contracts repo and docs repo
+
+1. Verify `<CONTRACTS_REPO_PATH>` exists and is a git repository:
+   `git -C <CONTRACTS_REPO_PATH> rev-parse --is-inside-work-tree`.
+2. Verify `<DOCS_REPO_PATH>` exists and is a git repository.
+3. Confirm `<CONTRACTS_REPO_PATH>` is **not** the same as
+   `<DOCS_REPO_PATH>`.
+4. Confirm the docs repo's working tree is clean **enough** to make
+   reviewable edits (no unrelated unstaged changes that would muddy the
+   diff). Warn but continue if not.
+
+## Step 4 — Verify base and head commits
+
+```
+git -C <CONTRACTS_REPO_PATH> rev-parse --verify <BASE_COMMIT>^{commit}
+git -C <CONTRACTS_REPO_PATH> rev-parse --verify <HEAD_COMMIT>^{commit}
+```
+
+Both must resolve. If either fails:
+
+- Interactive: ask the user to fetch the right revision.
+- Automatic: stop with a clear error.
+
+Confirm `<BASE_COMMIT>` is an ancestor of `<HEAD_COMMIT>`:
+
+```
+git -C <CONTRACTS_REPO_PATH> merge-base --is-ancestor <BASE_COMMIT> <HEAD_COMMIT>
+```
+
+If not, warn (the diff will still be computed, but the relationship is
+unusual — record it in the report).
+
+## Step 5 — Compute the contracts diff
+
+```
+git -C <CONTRACTS_REPO_PATH> diff --stat <BASE_COMMIT>..<HEAD_COMMIT>
+git -C <CONTRACTS_REPO_PATH> diff <BASE_COMMIT>..<HEAD_COMMIT>
+```
+
+Persist the output for use in Steps 6–10. Also gather:
+
+```
+git -C <CONTRACTS_REPO_PATH> log --pretty=oneline <BASE_COMMIT>..<HEAD_COMMIT>
+```
+
+…to label classifications in the report.
+
+This diff is the **only** accepted source of truth for what changed.
+Anything in chat (PR descriptions, summaries, pasted snippets) is
+context, not authority.
+
+## Step 6 — Resolve the target docs slice
+
+Resolve and verify each slice path on disk:
+
+| Variable                       | Source                                         |
+| ------------------------------ | ---------------------------------------------- |
+| `<DOCS_CONTENT_ROOT>`          | `docs.content_root`                            |
+| `<LIBRARY_DOCS_ROOT>`          | `docs.library_root`                            |
+| `<VERSION_DOCS_ROOT>`          | `docs.version_root`                            |
+| `<API_REFERENCE_PATH>`         | `docs.api_reference_path`                      |
+| `<NAV_CONFIG_PATH>`            | `docs.nav_config_path`                         |
+| `<LOCAL_DOCS_CONVENTIONS_PATH>`| `docs.local_conventions_path`                  |
+| `<PRODUCT_INDEX_PATH>`         | `docs.product_index_path`                      |
+| `<VERSION_INDEX_PATH>`         | `docs.version_index_path`                      |
+
+For each, check that the file or directory exists under
+`<DOCS_REPO_PATH>`. For missing pieces:
+
+1. If `docs.library_root` exists but `docs.version_root` does not, stop;
+   a new version needs an explicit setup decision.
+2. If `docs.api_reference_path` is missing and the scoped run requires
+   API reference updates, create it and record the assumption.
+3. If `docs.nav_config_path` is missing, stop; do not invent navigation.
+4. If `docs.local_conventions_path` is missing, fall back to repo-root
+   `AGENTS.md` and record the fallback.
+
+## Step 7 — Read local docs conventions
+
+If `<LOCAL_DOCS_CONVENTIONS_PATH>` exists, read it and treat it as
+authoritative for that docs slice (formatting, code style in snippets,
+section ordering, naming conventions, table formats, etc.).
+
+If it does not exist, fall back to the repo-root `AGENTS.md` (e.g.
+`<DOCS_REPO_PATH>/AGENTS.md`) for global rules and record the fallback.
+
+For Sui specifically:
+
+- Local conventions live at `content/contracts-sui/AGENTS.md`.
+- API Reference function entry order is **description, then `Aborts ...`,
+  then `Emits ...`**, with only NOTE/INFO/WARNING blocks afterwards.
+
+## Step 8 — Inspect contract changes
+
+From the diff in Step 5, group hunks by file and by language construct.
+For each changed file, record:
+
+- File path (relative to `<CONTRACTS_REPO_PATH>`).
+- Whether it is part of the public API surface (sources/, package
+  manifests) or internal (tests/, scripts/, internal helpers).
+- The high-level construct affected: module, struct, function, constant,
+  event, error, ability, capability, doc comment.
+
+Skip files outside the contracts library's documented surface (CI,
+internal tooling, vendored libs). Record what was skipped.
+
+## Step 9 — Extract or compare the public API surface
+
+Use `references/checks/extract_public_api.md` as the extraction
+specification to extract the public API surface at both `<BASE_COMMIT>`
+and `<HEAD_COMMIT>`. Use `references/checks/compare_public_api.md` as
+the comparison spec. If executable project tooling exists, prefer it and
+record the command. Produce a structured list:
+
+- Added modules / packages.
+- Removed modules / packages.
+- Added public functions, with signatures.
+- Removed public functions.
+- Changed function signatures (parameter types/order, return type,
+  visibility, abilities).
+- Added or changed structs/types and their fields/abilities.
+- Added or removed constants.
+- Added or removed events.
+- Added or removed errors / abort codes.
+- Changed doc comments on public items.
+
+The spec is language-agnostic; for `MOVE_SUI`, parse `module ...`
+declarations, `public fun`/`entry` signatures, `struct ... has ...`
+declarations, `const`s, error constants (`E*`), and event structs.
+
+## Step 10 — Classify changes
+
+Apply `references/rules/change-classification.md` to the structured
+list from Step 9 and to the raw diff from Step 5. Each change becomes
+one or more rows of:
+
+| File / construct | Classification | Evidence (commit, hunk) |
+
+Classification values are exactly the names in
+`references/rules/change-classification.md`.
+
+## Step 11 — Decide required docs updates
+
+For each classified change, look up the corresponding row in
+`references/rules/doc-update-matrix.md`. The matrix tells you:
+
+- Whether API reference must update.
+- Whether a guide, tutorial, or explanation must update.
+- Whether examples must update.
+- Whether navigation must update.
+- Whether changelog/release notes must update.
+- Whether a security warning is required.
+- The default behavior in automatic mode.
+- The questions to ask in interactive mode.
+
+Aggregate the required updates per docs page so the same page is not
+edited multiple times in incompatible ways.
+
+Apply `<DOCS_UPDATE_SCOPE>`:
+
+- `full`: keep every matrix-required update.
+- `api-only`: keep API reference, API source-link, API stale identifier,
+  and API navigation updates only; report other required work as skipped.
+- `guides-only`: keep guide, tutorial, explanation, and snippet updates;
+  do not regenerate API reference pages.
+- `targeted:<paths>`: keep only listed paths plus navigation changes
+  required for those paths; report omitted matrix-required work.
+
+In `interactive` mode, present the aggregated plan and wait for
+confirmation before broad rewrites of guides, tutorials, or
+explanations. API reference updates proceed without confirmation but
+follow `references/rules/api-reference-rules.md`.
+
+## Step 12 — Update API reference
+
+Follow `references/rules/api-reference-rules.md`:
+
+1. For each touched module, read the existing API reference page (if
+   any) under `<API_REFERENCE_PATH>`.
+2. Regenerate the structured sections (Types, Functions, Events, Errors)
+   from the source.
+3. Preserve existing prose that is still accurate; replace prose that no
+   longer matches the source.
+4. Honor the entry order from `<LOCAL_DOCS_CONVENTIONS_PATH>` (for Sui:
+   description, then Aborts, then Emits, then NOTE/INFO/WARNING).
+5. If a public item has weak or missing source comments, generate only
+   the deterministic parts and add a `needs-human-review` report item.
+   Add inline TODO comments only when there is no better accurate prose;
+   unresolved TODOs fail validation when
+   `automation.fail_on_unresolved_placeholders: true`.
+6. Update source links / version pins (`APIGithubLinkHeader` for Sui)
+   to point to `<RELEASE_VERSION>` (or `<HEAD_COMMIT>` if no matching
+   tag exists).
+
+## Step 13 — Update guides, tutorials, and explanations
+
+For every guide/tutorial/explanation flagged in Step 11:
+
+1. Use `references/rules/diataxis-rules.md` to confirm the page is
+   still in the right Diátaxis category. If not, propose a move
+   (interactive) or record it as a `needs-human-review` finding
+   (automatic).
+2. Apply the matching template (`references/templates/guide-template.md`,
+   `references/templates/tutorial-template.md`,
+   `references/templates/explanation-template.md`) when creating new
+   pages.
+3. When updating existing pages, edit only the sections affected by the
+   change set. Do not rewrite working content.
+4. Update inline code snippets to match the new API. Update prose that
+   describes signatures, arguments, abort conditions, or events.
+5. Add or update security warnings according to
+   `security.warning_style` and `security.require_security_sections_for`
+   from config.
+
+## Step 14 — Update examples
+
+If the docs slice has an `examples_root`, update it. If examples live as
+fenced code blocks inside MDX, update those.
+
+- Replace stale identifiers, package addresses, and signatures.
+- Run `examples.compile_command` if set; otherwise apply
+  `examples.snippet_validation` (e.g. `syntax`-only validation).
+- Do not create new example projects unless the matrix requires one
+  (e.g. `New module/package`).
+
+## Step 15 — Update navigation / sidebar
+
+Open `<NAV_CONFIG_PATH>` and apply the deltas:
+
+- Add new modules to the `Packages` and `API Reference` folders (or the
+  equivalent labels for the slice).
+- Remove entries for deleted modules.
+- Rename entries when modules were renamed.
+- Preserve existing order otherwise; insert new entries alphabetically
+  within their folder.
+- Do **not** create or edit `meta.json` files. The docs repo uses
+  centralized JSON navigation under `src/navigation/`.
+
+For Sui specifically, edit `src/navigation/sui/current.json`.
+
+## Step 16 — Validate
+
+Run, in order. The files under `references/checks/` are validation
+specs, not guaranteed executables; use project tooling or implement the
+checks directly from the specs.
+
+1. **Public API coverage**: every public item from Step 9 has a
+   reference entry. Use `references/checks/detect_missing_pages.md`.
+2. **Stale identifiers**: search the docs slice for removed names,
+   package ids, addresses, and old signatures.
+   `references/checks/find_stale_identifiers.md`.
+3. **Code snippets**: parse fenced code blocks per
+   `examples.snippet_validation`. `references/checks/check_code_snippets.md`.
+4. **Links**: validate internal links and anchors within the slice.
+   `references/checks/check_links.md`.
+5. **Navigation consistency**: every doc page reachable via
+   `<NAV_CONFIG_PATH>` exists, and every existing reference page is
+   reachable via navigation. `references/checks/check_nav_consistency.md`.
+6. **Placeholder check**: no unresolved `<TODO>`, `<FILL>`, or template
+   placeholder tokens remain. If
+   `automation.fail_on_unresolved_placeholders: true` and any are
+   found, stop.
+
+Each validation produces a pass/fail status and a list of findings. All
+findings go into the report.
+
+## Step 17 — Produce docs PR summary
+
+Walk through `references/rules/docs-pr-checklist.md`. Do not skip
+items. Mark each as pass/fail/N/A with one-line evidence.
+
+Then fill out the compact
+`references/reports/docs-sync-report-template.md` in the final run
+output. Do not create `docs-sync-report.md` unless the user asks.
+
+The report includes a suggested PR title and body, ready for `gh pr
+create`.
+
+## Step 18 — Record assumptions and unresolved issues
+
+Anything that wasn't directly evidenced by the diff or the config goes
+into the report as either:
+
+- An **assumption** (the agent picked a reasonable default and continued).
+- An **unresolved TODO** (the agent could not safely proceed and left a
+  marker for a human).
+
+Both lists must be exhaustive. The goal is for the next person — human
+or agent — to pick up the work without re-running the whole process.
diff --git a/skills/docs-sync/references/checks/README.md b/skills/docs-sync/references/checks/README.md
new file mode 100644
index 00000000..e00ad816
--- /dev/null
+++ b/skills/docs-sync/references/checks/README.md
@@ -0,0 +1,31 @@
+# docs-sync helper scripts
+
+These files are validation and extraction **specs**, not executable
+scripts. They define the inputs, outputs, failure conditions, and
+interpretation rules for each helper the agent uses during a
+`docs-sync` run.
+
+The agent should pick the most appropriate concrete command in its
+runtime environment (rg, grep, language-specific parsers, project
+tooling) to satisfy each helper's contract. If the project ships a real
+implementation, prefer it and record the command used.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| [extract_public_api.md](./extract_public_api.md) | Extract the public API surface at a given commit. |
+| [compare_public_api.md](./compare_public_api.md) | Diff two extracted surfaces and produce a structured change list. |
+| [detect_missing_pages.md](./detect_missing_pages.md) | Find public items that lack a reference entry. |
+| [check_links.md](./check_links.md) | Validate internal links and anchors inside the slice. |
+| [check_code_snippets.md](./check_code_snippets.md) | Validate fenced code blocks per `examples.snippet_validation`. |
+| [check_nav_consistency.md](./check_nav_consistency.md) | Cross-check navigation config against actual content. |
+| [find_stale_identifiers.md](./find_stale_identifiers.md) | Find references to removed names, addresses, signatures. |
+
+Each helper:
+
+- Lists explicit inputs.
+- Lists expected outputs in a stable, parseable shape.
+- Lists failure conditions that should make the agent stop or warn.
+- Lists how the agent should interpret the result (block the run? add
+  a `needs-human-review` finding? auto-fix?).
diff --git a/skills/docs-sync/references/checks/check_code_snippets.md b/skills/docs-sync/references/checks/check_code_snippets.md
new file mode 100644
index 00000000..f1a8264a
--- /dev/null
+++ b/skills/docs-sync/references/checks/check_code_snippets.md
@@ -0,0 +1,78 @@
+# check_code_snippets spec
+
+Validate fenced code blocks in the docs slice per the slice's
+`examples.snippet_validation` setting.
+
+## Inputs
+
+- `LIBRARY_DOCS_ROOT` — `docs.library_root` from config.
+- `LANGUAGE` — `library.language` from config.
+- `VALIDATION_LEVEL` — `examples.snippet_validation`:
+  - `none` — skip validation entirely.
+  - `syntax` — parse code blocks and report syntax errors.
+  - `compile` — run `examples.compile_command` (if set) on
+    extracted snippets.
+  - `test` — same as `compile` but also run tests.
+- `COMPILE_COMMAND` — `examples.compile_command` (if set).
+- `EXAMPLES_ROOT` — `examples.examples_root` (if set; otherwise empty
+  and only embedded snippets are checked).
+
+## Output
+
+```
+{
+  "snippets_total": <int>,
+  "snippets_validated": <int>,
+  "syntax_errors": [
+    {"file": "<path>", "line": <int>, "language": "<lang>",
+     "message": "<parser message>"}
+  ],
+  "compile_errors": [
+    {"file": "<path>", "line": <int>, "command": "<cmd>",
+     "stdout": "<...>", "stderr": "<...>"}
+  ]
+}
+```
+
+## Procedure
+
+1. Walk every `*.mdx` under `<LIBRARY_DOCS_ROOT>`.
+2. Extract fenced code blocks. Track:
+   - File path and starting line number.
+   - Fence info string (` ```move`, ` ```cairo`, etc.).
+   - Block content.
+3. For each block whose language matches `LANGUAGE` (or is plausibly
+   the slice's language — for `MOVE_SUI`: `move`, `move-sui`,
+   `move2024`):
+   - If `VALIDATION_LEVEL == none`: skip.
+   - If `VALIDATION_LEVEL == syntax`: parse with the language's
+     parser. Record a `syntax_errors` entry on failure.
+   - If `VALIDATION_LEVEL in {compile, test}`:
+     a. Extract to a temporary file under a scratch project.
+     b. Run `COMPILE_COMMAND` against the scratch project.
+     c. Record `compile_errors` on non-zero exit.
+4. If `EXAMPLES_ROOT` is set, validate the project there separately
+   using the same level.
+
+## Failure conditions
+
+- The configured parser/compiler is not available → record once at
+  the run level and downgrade to the next-lower validation level
+  (e.g. `compile` → `syntax`). Note the downgrade in the report.
+- A snippet has no language tag → skip and add a soft warning;
+  unmarked code blocks are not part of the public docs guarantee.
+
+## Interpretation
+
+- `syntax_errors` and `compile_errors` are hard failures for the
+  Code snippets validation step in `process.md`.
+- Automatic mode attempts up to one round of mechanical fixes for
+  obvious issues (stale identifiers, renamed items per
+  `compare_public_api`). After one round, remaining failures are
+  recorded as `needs-human-review`.
+- Interactive mode prints the failure count and the first few
+  examples and asks whether to auto-fix or leave alone.
+
+Snippets in tutorials and how-to guides have a higher bar (they
+should compile when possible). Snippets inside reference entries are
+typically illustrative; `syntax`-level validation is enough.
diff --git a/skills/docs-sync/references/checks/check_links.md b/skills/docs-sync/references/checks/check_links.md
new file mode 100644
index 00000000..f608fb5e
--- /dev/null
+++ b/skills/docs-sync/references/checks/check_links.md
@@ -0,0 +1,74 @@
+# check_links spec
+
+Validate internal links and anchors inside the docs slice.
+
+## Inputs
+
+- `LIBRARY_DOCS_ROOT` — `docs.library_root` from config.
+- `VERSION_DOCS_ROOT` — `docs.version_root` from config.
+- `NAV_CONFIG_PATH` — `docs.nav_config_path` from config.
+- `EXTERNAL_CHECK` — `false` by default. When `false`, do not fetch
+  external URLs.
+
+## Output
+
+```
+{
+  "broken_internal_links": [
+    {"file": "<path>", "line": <int>, "href": "<href>", "reason": "<why>"}
+  ],
+  "broken_anchors": [
+    {"file": "<path>", "line": <int>, "href": "<href>", "anchor": "<id>"}
+  ],
+  "broken_relative_paths": [
+    {"file": "<path>", "line": <int>, "href": "<href>"}
+  ],
+  "external_links_skipped": [
+    {"file": "<path>", "line": <int>, "href": "<href>"}
+  ]
+}
+```
+
+## Procedure
+
+1. Walk every `*.mdx` file under `<LIBRARY_DOCS_ROOT>`.
+2. For each markdown link `[text](href)` (including images and JSX
+   attribute hrefs):
+   - If `href` starts with `http://` or `https://` and
+     `EXTERNAL_CHECK` is false, record under `external_links_skipped`
+     and skip.
+   - If `href` starts with `/`, treat as a docs-site root-relative
+     URL. Resolve to a content path using the docs framework rules:
+     `/contracts-sui/1.x/api/access` → `content/contracts-sui/1.x/api/access.mdx`.
+   - If `href` starts with `./` or `../`, resolve relative to the
+     current file.
+   - If `href` contains a `#fragment`, split into path and anchor.
+3. For each resolved path, check that the file exists.
+4. For each anchor, parse the target file and confirm the anchor is
+   declared (look for `id="..."` and `<a id="..."></a>`, also any
+   `[#anchor]` syntax this slice uses).
+5. For navigation: parse `<NAV_CONFIG_PATH>` JSON, resolve every
+   `url` to a content file the same way, and record any nav entry
+   that points nowhere as a `broken_internal_links` finding.
+
+## Failure conditions
+
+- A file under `<LIBRARY_DOCS_ROOT>` cannot be parsed as MDX → record
+  with `reason: "parse_error"` and continue.
+- `<NAV_CONFIG_PATH>` cannot be parsed as JSON → return a clear
+  failure; the run cannot complete navigation validation.
+
+## Interpretation
+
+- Any `broken_internal_links`, `broken_anchors`, or
+  `broken_relative_paths` entry is a `fail` for the Links validation
+  step in `process.md`.
+- Automatic mode tries to auto-fix:
+  - If the broken anchor was renamed in this run (per
+    `compare_public_api`), repoint the link.
+  - If the broken file path was renamed in this run, repoint the
+    link.
+  - Otherwise, leave the link and add a `needs-human-review`
+    finding.
+- Interactive mode lists each finding once and asks "auto-fix where
+  possible? (yes/no)" — never re-asks within the same run.
diff --git a/skills/docs-sync/references/checks/check_nav_consistency.md b/skills/docs-sync/references/checks/check_nav_consistency.md
new file mode 100644
index 00000000..7153b306
--- /dev/null
+++ b/skills/docs-sync/references/checks/check_nav_consistency.md
@@ -0,0 +1,77 @@
+# check_nav_consistency spec
+
+Cross-check the slice's navigation config against the actual content
+on disk.
+
+## Inputs
+
+- `NAV_CONFIG_PATH` — `docs.nav_config_path` from config.
+- `LIBRARY_DOCS_ROOT` — `docs.library_root` from config.
+- `VERSION_DOCS_ROOT` — `docs.version_root` from config.
+- `URL_TO_PATH` — function that maps a nav `url` to a content path.
+  For Sui: `/contracts-sui/1.x/api/access` →
+  `content/contracts-sui/1.x/api/access.mdx`.
+- `REQUIRED_FOLDERS` — `navigation.required_folders` from config (if
+  set).
+
+## Output
+
+```
+{
+  "nav_entries_pointing_nowhere": [
+    {"name": "<nav label>", "url": "<url>", "expected_path": "<path>"}
+  ],
+  "pages_not_in_nav": [
+    {"path": "<path>", "url_guess": "<url>"}
+  ],
+  "missing_required_folders": ["<folder name>", ...],
+  "meta_json_files_present": ["<path>", ...]
+}
+```
+
+## Procedure
+
+1. Parse `<NAV_CONFIG_PATH>` as JSON. Walk it recursively and
+   collect every `{ "type": "page", "url": "..." }` entry.
+2. For each `url`, compute `URL_TO_PATH(url)`. If the file does not
+   exist under `<DOCS_REPO_PATH>`, record under
+   `nav_entries_pointing_nowhere`.
+3. Walk every `*.mdx` under `<LIBRARY_DOCS_ROOT>`. For each, compute
+   the canonical url. If no nav entry points to it, record under
+   `pages_not_in_nav`.
+4. For each name in `REQUIRED_FOLDERS`, check the nav structure has
+   a folder of that name at the expected level. Record missing names
+   under `missing_required_folders`.
+5. Walk `<LIBRARY_DOCS_ROOT>` for any `meta.json` files. Record their
+   paths under `meta_json_files_present`. (For slices where
+   `navigation.forbid_meta_json: true`, this is always a fail.)
+
+## Failure conditions
+
+- `<NAV_CONFIG_PATH>` cannot be read or parsed → return a clear
+  failure; the run cannot validate navigation.
+- The slice has no canonical url-to-path mapping (i.e. the docs
+  framework's routing is unknown) → return a soft failure and skip
+  the cross-check; record the limitation in the report.
+
+## Interpretation
+
+- `nav_entries_pointing_nowhere` is a hard fail.
+- `pages_not_in_nav` is a hard fail unless the page is explicitly
+  unlisted (e.g. drafts), which the slice does not currently use —
+  flag every such page.
+- `missing_required_folders` is a hard fail.
+- `meta_json_files_present` is a hard fail when
+  `navigation.forbid_meta_json: true`.
+
+Automatic mode auto-fixes the obvious cases:
+
+- For pages added in this run with no nav entry, insert one
+  alphabetically inside the matching folder per
+  `navigation.required_folders` and the existing folder structure.
+- For nav entries pointing at pages deleted in this run, remove the
+  entry.
+
+It does not auto-fix `meta_json_files_present`; deleting `meta.json`
+files outside the run's scope is too aggressive. Surface the
+finding so the slice owner can act.
diff --git a/skills/docs-sync/references/checks/compare_public_api.md b/skills/docs-sync/references/checks/compare_public_api.md
new file mode 100644
index 00000000..3723b249
--- /dev/null
+++ b/skills/docs-sync/references/checks/compare_public_api.md
@@ -0,0 +1,98 @@
+# compare_public_api spec
+
+Diff two extracted public API surfaces (output of
+`extract_public_api`) and produce a structured change list.
+
+## Inputs
+
+- `BASE_SURFACE` — JSON output of `extract_public_api(<BASE_COMMIT>)`.
+- `HEAD_SURFACE` — JSON output of `extract_public_api(<HEAD_COMMIT>)`.
+
+## Output
+
+```
+{
+  "added_modules":   [ {"package": "...", "module": "...", "path": "..."} ],
+  "removed_modules": [ ... ],
+  "renamed_modules": [ {"from": {...}, "to": {...}} ],
+
+  "added_items":   [ {"package": "...", "module": "...", "kind": "...", "name": "...", "signature": "..."} ],
+  "removed_items": [ ... ],
+  "changed_items": [
+    {
+      "package": "...",
+      "module": "...",
+      "kind": "...",
+      "name": "...",
+      "before": { "signature": "...", "abilities": [...], "type_parameters": [...], "doc_summary": "...", "doc_aborts": [...], "doc_emits": [...] },
+      "after":  { "signature": "...", "abilities": [...], "type_parameters": [...], "doc_summary": "...", "doc_aborts": [...], "doc_emits": [...] },
+      "diff_dimensions": ["signature" | "abilities" | "type_parameters" | "visibility" | "doc_only" | "abort_set" | "emit_set"]
+    }
+  ],
+
+  "deprecation_added": [ ... ],
+  "deprecation_removed": [ ... ]
+}
+```
+
+## Procedure
+
+1. Build a key for each item: `<package>::<module>::<name>::<kind>`.
+2. Compute set differences:
+   - `added` = items in `HEAD_SURFACE` not in `BASE_SURFACE`.
+   - `removed` = items in `BASE_SURFACE` not in `HEAD_SURFACE`.
+   - `intersection` = items in both.
+3. For each item in `intersection`, compute `diff_dimensions`:
+   - `signature` if the canonical signature string changed.
+   - `abilities` if the abilities list changed (structs).
+   - `type_parameters` if the type parameter list changed.
+   - `visibility` if visibility changed (e.g. `public(friend)` →
+     `public`).
+   - `doc_only` if only `doc_summary`, `doc_aborts`, or `doc_emits`
+     changed and nothing structural.
+   - `abort_set` if `abort_sites` differs.
+   - `emit_set` if `emit_sites` differs.
+4. Detect rename candidates: items removed from one module and added
+   to another with a matching signature and similar name. Emit them
+   as `renamed_modules` (or `renamed_items`) only when confidence is
+   high (signatures and abilities both match). Otherwise leave them
+   in `removed_items` + `added_items`.
+5. Detect deprecation transitions: items that gained
+   `deprecated: true` between commits go to `deprecation_added`;
+   items that lost it go to `deprecation_removed`.
+
+## Failure conditions
+
+- Inputs missing or malformed → stop.
+- More than 50% of items show `signature` change in a single run →
+  warn (likely a parser drift between extractor versions, not a real
+  refactor). The agent should sanity-check before classifying.
+
+## Interpretation
+
+The output of this helper is the canonical structured input for
+`references/rules/change-classification.md`. The agent maps `diff_dimensions` and
+membership in added/removed/changed sets to classification names:
+
+- `added_modules` → `New module/package`.
+- `removed_modules` → `Removed feature` (+ `Breaking change`
+  secondary).
+- `added_items` of kind `function` → `New public function`.
+- `added_items` of kind `event` → `Changed event`.
+- `removed_items` → `Removed feature` (+ `Breaking change`).
+- `changed_items` with `diff_dimensions` containing `signature`,
+  `type_parameters`, or `visibility` → `Changed function signature`
+  (+ `Breaking change` if not additive).
+- `changed_items` with `abort_set` only → `Changed abort/error
+  condition`.
+- `changed_items` with `emit_set` only → `Changed event`.
+- `changed_items` with `abilities` only → `Changed ability/ownership
+  semantics`.
+- `changed_items` with `doc_only` only → `Documentation-only source
+  comment change`.
+- `deprecation_added` → `Deprecated feature`.
+
+The agent must still apply the secondary `Security-sensitive
+behavior` classification by inspecting which modules / functions
+were touched (per the trigger list in
+`references/rules/change-classification.md`).
diff --git a/skills/docs-sync/references/checks/detect_missing_pages.md b/skills/docs-sync/references/checks/detect_missing_pages.md
new file mode 100644
index 00000000..f170e7d0
--- /dev/null
+++ b/skills/docs-sync/references/checks/detect_missing_pages.md
@@ -0,0 +1,75 @@
+# detect_missing_pages spec
+
+Find public items that lack a reference entry in the docs slice.
+
+## Inputs
+
+- `HEAD_SURFACE` — JSON output of `extract_public_api(<HEAD_COMMIT>)`.
+- `API_REFERENCE_PATH` — `docs.api_reference_path` from config
+  (relative to `<DOCS_REPO_PATH>`).
+- `LAYOUT` — `api_reference_layout.page_per` from config
+  (`package` or `module`).
+- `ANCHOR_CONVENTION` — how reference anchors are formed
+  (default for Sui: `<module>-<item>`).
+
+## Output
+
+```
+{
+  "missing_modules": [
+    {"package": "...", "module": "...", "expected_path": "<path>"}
+  ],
+  "missing_items": [
+    {"package": "...", "module": "...", "kind": "...", "name": "...",
+     "expected_anchor": "<anchor>", "expected_path": "<path>"}
+  ],
+  "orphan_pages": [
+    {"path": "<path>", "reason": "no matching public item"}
+  ]
+}
+```
+
+## Procedure
+
+1. For each module in `HEAD_SURFACE`, compute the expected page path:
+   - `LAYOUT == "package"`:
+     `<API_REFERENCE_PATH>/<package>.mdx`.
+   - `LAYOUT == "module"`:
+     `<API_REFERENCE_PATH>/<package>/<module>.mdx`.
+2. Check that the file exists. If not, record under
+   `missing_modules`.
+3. If the file exists, parse it for declared anchors (any `id="..."`
+   on `<APIItem>` blocks, plus literal `<a id="..."></a>` tags).
+4. For each `item` in the module, compute the expected anchor per
+   `ANCHOR_CONVENTION` (default `<module>-<item>`).
+5. If the anchor is not present in the page, record under
+   `missing_items`.
+6. Walk every existing page under `<API_REFERENCE_PATH>`. For each,
+   parse anchors and confirm at least one item in `HEAD_SURFACE`
+   maps to it. If none does, record under `orphan_pages`.
+
+## Failure conditions
+
+- `<API_REFERENCE_PATH>` does not exist on disk → record at the run
+  level (the agent already handles this in process.md Step 6).
+- Parsing an MDX page failed → record the page in
+  `orphan_pages` with reason `parse_error` and continue.
+
+## Interpretation
+
+- `missing_modules` is a hard finding. The agent must create the
+  missing page (automatic mode) or surface it for confirmation
+  (interactive mode).
+- `missing_items` is a hard finding for items in `HEAD_SURFACE`. The
+  agent must add the entry to the page in canonical source order.
+- `orphan_pages` is a soft finding. Reasons include:
+  - The item was renamed (likely paired with a `missing_items`
+    entry).
+  - The item was removed in this run.
+  - The page documents something no longer in the public surface
+    extractor (possible parser issue — surface as a warning).
+
+In the report, `orphan_pages` is reviewed against `removed_items`
+from `compare_public_api`. Pages whose only items were removed should
+be deleted (Removed feature classification); pages whose orphan
+status is unexplained become `needs-human-review`.
diff --git a/skills/docs-sync/references/checks/extract_public_api.md b/skills/docs-sync/references/checks/extract_public_api.md
new file mode 100644
index 00000000..fdf03acb
--- /dev/null
+++ b/skills/docs-sync/references/checks/extract_public_api.md
@@ -0,0 +1,123 @@
+# extract_public_api spec
+
+Extract the public API surface of a contracts library at a given
+commit, in a stable, comparable form.
+
+## Inputs
+
+- `CONTRACTS_REPO_PATH` — local path to the contracts repo.
+- `COMMIT_SHA` — commit to inspect (`<BASE_COMMIT>` or `<HEAD_COMMIT>`).
+- `LANGUAGE` — from `library.language` in config (e.g. `MOVE_SUI`).
+- `SOURCE_GLOBS` — globs for source files (default per language; for
+  `MOVE_SUI`: `**/sources/**/*.move`, excluding `**/tests/**`,
+  `**/examples/**`, `**/scripts/**`).
+
+## Output
+
+A structured JSON-shaped object with one entry per public item:
+
+```
+{
+  "commit": "<COMMIT_SHA>",
+  "language": "<LANGUAGE>",
+  "modules": [
+    {
+      "package": "<package_name>",
+      "module": "<module_name>",
+      "path": "<relative path inside CONTRACTS_REPO_PATH>",
+      "doc_summary": "<first paragraph of /// comments on the module>",
+      "items": [
+        {
+          "kind": "function" | "struct" | "const" | "error" | "event" | "type_alias",
+          "name": "<item_name>",
+          "signature": "<canonical one-line form>",
+          "type_parameters": ["<T: bounds>", ...],
+          "abilities": ["key", "store", ...],          // structs only
+          "visibility": "public" | "public(friend)" | "entry" | ...,
+          "doc_summary": "<first paragraph of ///>",
+          "doc_aborts": ["Aborts with EX if Y.", ...], // functions only
+          "doc_emits":  ["Emits Z on W.", ...],         // functions only
+          "abort_sites": ["EX", "EY"],                  // discovered from code
+          "emit_sites":  ["Z"],                         // discovered from code
+          "deprecated": true | false,
+          "deprecated_message": "<text|null>"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Canonical signature form
+
+For determinism, normalize signatures:
+
+- One line, no trailing whitespace.
+- Spaces collapsed.
+- Type parameters ordered as in source.
+- Parameter names preserved verbatim.
+- Abilities preserved verbatim.
+
+## Procedure
+
+1. Create a unique temporary directory with `mktemp -d`.
+2. Resolve the commit in a detached temporary worktree:
+       git -C <CONTRACTS_REPO_PATH> worktree add --detach <tmpdir>/<short-sha> <COMMIT_SHA>
+   Use a temporary worktree so the main checkout is untouched. Do not
+   stash, reset, or otherwise mutate the caller's checkout.
+3. Glob source files per `SOURCE_GLOBS` inside the temporary worktree.
+4. Parse each file:
+   - For `MOVE_SUI`: parse `module ::name;` declarations, `public fun`
+     / `entry fun` signatures, `struct ... has ...`, `const`, error
+     constants (`E*`), event structs (those passed to `event::emit`).
+   - Use a Move parser if available; otherwise a tolerant
+     regex-based extractor with the patterns documented in
+     `<LOCAL_DOCS_CONVENTIONS_PATH>`.
+5. Walk function bodies (best-effort) to record abort and emit sites:
+   - For abort sites, look for `abort <ECONST>` and
+     `assert!(..., <ECONST>)`.
+   - For emit sites, look for `event::emit(...)` and infer the event
+     struct from the argument's constructor.
+6. Normalize and emit JSON.
+7. Remove the temporary worktree:
+       git -C <CONTRACTS_REPO_PATH> worktree remove <tmpdir>/<short-sha>
+   Then remove the temporary directory.
+
+## Failure conditions
+
+- Commit cannot be resolved → stop.
+- No source files matched globs → stop. Likely a misconfigured
+  language or path.
+- Parse errors on >5% of files → continue but add a warning per
+  failed file. The agent should record this in the report.
+- Move parser unavailable AND regex extractor produced unbalanced
+  output (e.g. unmatched braces in signatures) → fall back to
+  conservative output: include items the agent can fully recover,
+  list partial recoveries as `needs-human-review` findings.
+
+## Interpretation
+
+The agent calls this twice: once for `<BASE_COMMIT>`, once for
+`<HEAD_COMMIT>`. The result is consumed by `compare_public_api.md`.
+
+If extraction is clearly wrong (e.g. zero items recovered for a
+module the diff shows changes in), do not proceed with classification
+based on it. Stop and report which module's surface could not be
+extracted.
+
+## Notes for non-Move languages
+
+The same shape applies to other contracts languages by changing the
+parser. Per language hint:
+
+- `CAIRO`: parse `mod`, `#[external(v0)]` / `#[generate_trait]`,
+  `fn`, `struct`, `enum`, `event`. Abilities/abilities are not
+  applicable; visibility is.
+- `STYLUS`: parse Rust crates that compile to WASM; treat
+  `#[external]` items as public.
+- `SOLIDITY`: parse `contract`, `library`, `interface`,
+  `function`, `event`, `error`, `modifier`; treat `external` and
+  `public` as public surface.
+
+The agent should set `library.language` correctly in config; the
+extractor branches on it.
diff --git a/skills/docs-sync/references/checks/find_stale_identifiers.md b/skills/docs-sync/references/checks/find_stale_identifiers.md
new file mode 100644
index 00000000..f36e848f
--- /dev/null
+++ b/skills/docs-sync/references/checks/find_stale_identifiers.md
@@ -0,0 +1,84 @@
+# find_stale_identifiers spec
+
+Find references to removed or renamed names, package ids, addresses,
+and function signatures inside the docs slice.
+
+## Inputs
+
+- `LIBRARY_DOCS_ROOT` — `docs.library_root` from config.
+- `COMPARE_RESULT` — output of `compare_public_api`, which lists
+  removed, renamed, and changed items.
+- `RELEASE_VERSION` — the new release tag.
+- `OLD_RELEASE_VERSIONS` — optional list of older release tags to
+  search for (legacy version pins in source links).
+- `KNOWN_ADDRESSES` — optional list of canonical package addresses
+  for the contracts library (current and previous), if the project
+  embeds them.
+
+## Output
+
+```
+{
+  "stale_function_names": [
+    {"file": "<path>", "line": <int>, "name": "<name>", "context": "<excerpt>"}
+  ],
+  "stale_event_names":   [ ... ],
+  "stale_error_names":   [ ... ],
+  "stale_struct_names":  [ ... ],
+  "stale_signatures":    [ {"file": ..., "line": ..., "before_signature": "<sig>", "after_signature": "<sig>", "context": "<excerpt>"} ],
+  "stale_addresses":     [ {"file": ..., "line": ..., "address": "<addr>"} ],
+  "stale_version_pins":  [ {"file": ..., "line": ..., "old_version": "<v>", "expected_version": "<RELEASE_VERSION>"} ]
+}
+```
+
+## Procedure
+
+1. Build the search lists from `COMPARE_RESULT`:
+   - `removed_function_names` ← every removed `function` item name.
+   - `removed_event_names` ← every removed `event` item name.
+   - `removed_error_names` ← every removed error const name.
+   - `removed_struct_names` ← every removed `struct` item name.
+   - `signature_diffs` ← every `changed_items` entry where
+     `signature` is in `diff_dimensions`.
+2. For each name in the removed lists, grep the slice
+   (`<LIBRARY_DOCS_ROOT>` recursively) and record matches.
+3. For each `signature_diff`, search for the `before` signature
+   string verbatim and record matches that are not already
+   accompanied by the `after` signature in the same block.
+4. For each url containing `OLD_RELEASE_VERSIONS` (e.g. `/blob/v1.0.0/`),
+   record under `stale_version_pins` if the release pinned for the
+   touched module is now `<RELEASE_VERSION>`.
+5. For each address in `KNOWN_ADDRESSES` that is not the current
+   canonical address, record under `stale_addresses`.
+
+## Failure conditions
+
+- `COMPARE_RESULT` missing or malformed → stop.
+- No `LIBRARY_DOCS_ROOT` on disk → stop (process.md Step 6 catches
+  this earlier).
+
+## Interpretation
+
+- Every entry in the output is a finding. Automatic mode applies
+  these rules:
+  - For renamed items where the rename is high-confidence (per
+    `compare_public_api`), substitute the new name in prose links
+    and headings, but **never** silently rewrite code blocks for
+    semantics.
+  - For `stale_version_pins`, update to `<RELEASE_VERSION>`.
+  - For `stale_addresses`, do not auto-update — addresses are
+    sensitive; surface as a hard finding.
+  - For `stale_function_names` / event / error / struct without a
+    rename target, surface as `needs-human-review`.
+- Interactive mode prints the count per category and asks whether
+  to auto-fix the safe categories.
+
+Heuristic rules to avoid false positives:
+
+- Skip matches inside fenced code blocks marked as
+  pre-`<RELEASE_VERSION>` snippets (look for a fence info string
+  containing the old version, or a heading like
+  "Before <release>:").
+- Skip matches inside a "Version history" section.
+- Skip matches where the surrounding text explicitly uses words like
+  "deprecated" or "removed in <version>".
diff --git a/skills/docs-sync/references/reports/docs-sync-report-template.md b/skills/docs-sync/references/reports/docs-sync-report-template.md
new file mode 100644
index 00000000..15783791
--- /dev/null
+++ b/skills/docs-sync/references/reports/docs-sync-report-template.md
@@ -0,0 +1,52 @@
+# docs-sync report template
+
+End each run with a compact Markdown report in the final response. Do
+not create a report file unless the user asks.
+
+Use repo-relative paths only. Do not include personal absolute
+filesystem paths.
+
+```markdown
+## docs-sync report
+
+- Mode: <interactive | automatic>
+- Library/version: <LIBRARY_ID> <DOCS_VERSION>
+- Contracts range: <BASE_COMMIT>..<HEAD_COMMIT>
+- Release/source pin: <RELEASE_VERSION | HEAD_COMMIT>
+- Scope: <DOCS_UPDATE_SCOPE>
+- Config: skills/docs-sync/config/libraries/<LIBRARY_ID>.yml
+
+### Change Summary
+
+| Construct | Classification | Docs impact | Evidence |
+|---|---|---|---|
+| <module/item> | <primary + secondary> | <pages/surfaces> | <commit/file/hunk> |
+
+### Files Updated
+
+- <path> — <what changed>
+
+### Validation
+
+- Public API coverage: pass | fail | skipped — <evidence>
+- Stale identifiers: pass | fail | skipped — <evidence>
+- Code snippets: pass | fail | skipped — <evidence>
+- Links: pass | fail | skipped — <evidence>
+- Navigation: pass | fail | skipped — <evidence>
+- Placeholders: pass | fail — <evidence>
+
+### Human Review
+
+- Assumptions: <none | bullets>
+- Needs human review: <none | bullets with path and reason>
+- Skipped by scope: <none | bullets>
+
+### Suggested PR
+
+Title: docs(<LIBRARY_ID>/<DOCS_VERSION>): sync to <RELEASE_VERSION>
+
+Body:
+- <high-signal summary bullet>
+- <validation bullet>
+- <reviewer note if needed>
+```
diff --git a/skills/docs-sync/references/rules/api-reference-rules.md b/skills/docs-sync/references/rules/api-reference-rules.md
new file mode 100644
index 00000000..2f25fbd3
--- /dev/null
+++ b/skills/docs-sync/references/rules/api-reference-rules.md
@@ -0,0 +1,238 @@
+# API reference rules
+
+API reference must be **accurate, complete, and deterministic**. The
+goal is that two agents running with the same contracts diff produce
+the same reference output (modulo prose carried over from existing
+pages).
+
+This file defines the contract between source comments and reference
+pages.
+
+---
+
+## Source comment format
+
+The agent reads source comments to populate API reference. The expected
+format depends on the language; for `MOVE_SUI`, doc comments use `///`
+attached to the item.
+
+### Required fields per item
+
+#### Module
+
+- One-paragraph summary of what the module does and who it's for.
+- Optional: a short rationale paragraph (which belongs in
+  Explanation, but if it is on the module it is acceptable in
+  Reference as a single paragraph).
+
+#### Public function
+
+1. **Description** — what the function does, in one short paragraph.
+2. **Aborts** — every abort condition reachable through this function,
+   one line each. Use the project's canonical phrasing
+   (`Aborts with <ErrorName> if <condition>.`).
+3. **Emits** — every event emitted, one line each
+   (`Emits <EventName> on <when>.`).
+4. **Notes / warnings** — only `NOTE`, `INFO`, or `WARNING` callouts
+   are allowed after the description / Aborts / Emits sections. The
+   order matters: see below.
+
+#### Struct / type
+
+- Summary describing the role of the struct.
+- Per-field one-line descriptions where the field name is not
+  self-explanatory.
+- Abilities and ownership semantics if non-obvious.
+
+#### Constant
+
+- One-line description if user-facing. Internal-only constants are
+  excluded from the public surface.
+
+#### Error
+
+- One line stating the condition the error represents.
+
+#### Event
+
+- Summary describing the event.
+- Per-field one-line descriptions.
+- A note on indexing if the event is meant for off-chain consumers.
+
+### Type parameters
+
+Document type parameters in the function or struct description, using
+the project's convention:
+
+- `<T: key + store>` — explain the constraints.
+- Note any phantom type parameters and what they encode.
+
+### Abilities, ownership, capabilities, access control
+
+- For structs: list `key`/`store`/`copy`/`drop` if non-obvious and
+  explain why each is present or absent (one line each).
+- For functions that gate behavior on a capability or sender check:
+  state the gate explicitly (`Requires <Cap>`, `Sender must be
+  <recorded principal>`).
+- For shared-object flows: state the sharing model.
+- For upgradeable modules: state the upgrade authority and what
+  changes when the module is upgraded.
+
+### Aborts and errors
+
+For each abort condition, the reference entry must say:
+
+- The error constant name (e.g. `ENotOwner`).
+- The condition that triggers it.
+
+Group multiple aborts into a list under the function entry's `Aborts`
+section, in source order.
+
+### Events
+
+For each event emitted, the reference entry must say:
+
+- The event struct name.
+- A short trigger condition.
+
+Cross-reference back to the events list at the top of the module page.
+
+### Examples in reference
+
+Inline code snippets are allowed inside `<APIItem>`-style entries when
+they help disambiguate calling syntax. They must:
+
+- Be language-tagged (` ```move`).
+- Be syntactically valid.
+- Use the same import / address conventions as
+  `<LOCAL_DOCS_CONVENTIONS_PATH>`.
+
+Do **not** include tutorials inside reference entries. If an example
+needs more than ~10 lines of context, link to a guide instead.
+
+---
+
+## Layout
+
+For Sui (and any slice with `api_reference_layout.page_per: package`):
+
+- One MDX file per package under `<API_REFERENCE_PATH>`.
+- Within the file, each module is a section using the configured
+  module section component (Sui: `<APIItem>`).
+- Each module section follows the canonical entry order from
+  `<LOCAL_DOCS_CONVENTIONS_PATH>`. For Sui:
+  1. Module description paragraph(s).
+  2. **Aborts** lines (when present).
+  3. **Emits** lines (when present).
+  4. NOTE / INFO / WARNING callouts (in that order).
+- Source links use the configured component
+  (Sui: `<APIGithubLinkHeader>`) pinned to `<RELEASE_VERSION>`.
+
+If the slice instead uses one page per module (set
+`api_reference_layout.page_per: module`), each module is its own MDX
+file under `<API_REFERENCE_PATH>/<package>/<module>.mdx`. The
+canonical entry order still applies inside each file.
+
+---
+
+## Handling missing or weak source comments
+
+The agent does **not** edit source comments by default. It reacts as
+follows:
+
+| Situation | Action |
+|---|---|
+| Public item has no `///` doc comment at all | Generate the deterministic signature/field list only. Add a `needs-human-review` finding; avoid inline TODOs unless the page would otherwise be misleading or incomplete. |
+| Doc comment exists but lacks `Aborts` for an abort the function clearly reaches | Generate the `Aborts` line from the source `assert!`/`abort` site when the condition is clear; otherwise add a `needs-human-review` finding. |
+| Doc comment exists but lacks `Emits` for an event clearly emitted | Generate the `Emits` line from the source `event::emit` site when the trigger is clear; otherwise add a `needs-human-review` finding. |
+| Doc comment is wrong (contradicts the code) | Replace the doc-side prose; do not edit source. Record in report. |
+| Doc comment is fine but the project's local conventions changed | Reformat in docs only. |
+
+### `automation.allow_source_comment_edits` true
+
+Only when this flag is `true` and the user explicitly asked to fix
+source comments may the agent edit `///` lines in the contracts repo.
+Even then:
+
+- Edits stay scoped to public items touched by the diff.
+- Each edit is recorded in the report (`Source comment edits` section).
+- The agent commits source-comment edits separately (one commit per
+  module), so they can be reviewed independently from the actual code
+  changes — but does not push.
+
+### Automatic mode
+
+Behavior with weak/missing comments:
+
+- Generate the deterministic parts (signature, errors list, events
+  list, fields list).
+- Avoid placeholder prose. Record missing or weak prose as
+  `needs-human-review` unless an inline TODO is the only honest output.
+- Continue. Do not block the run on weak comments.
+
+If `automation.fail_on_unresolved_placeholders: true`, any inline TODO
+or template placeholder fails Step 16. Prefer report findings over
+leaving placeholders in docs.
+
+### Interactive mode
+
+Behavior with weak/missing comments:
+
+- Surface the gap in the proposed plan: "Module `X` has 3 public
+  functions without descriptions. Generate deterministic entries and
+  flag for review, or pause for source-doc fill-in?"
+- Default action if the user does not answer: generate deterministic
+  entries and record `needs-human-review` findings.
+
+---
+
+## Source-comment edit rule (must)
+
+The agent MUST NOT modify source comments in the contracts repo unless
+**both** are true:
+
+1. `automation.allow_source_comment_edits: true` in the slice's config.
+2. The user explicitly asked for source-comment edits in the run prompt
+   (or in interactive responses).
+
+Even when both are true, the agent stays scoped to public items the
+diff already touched. The agent does not opportunistically rewrite
+unrelated comments.
+
+---
+
+## Determinism rules
+
+To keep API reference comparable run-to-run:
+
+1. **Sort sections in source order** when the source order is
+   meaningful (Sui modules use source order); sort alphabetically only
+   when the language has no inherent order.
+2. **Preserve prose carried over** verbatim if it is still accurate.
+   Do not rewrite for style.
+3. **Use exact identifier strings** from the source. Do not
+   pretty-print signatures.
+4. **Pin source links to a release tag** when one exists; otherwise
+   pin to `<HEAD_COMMIT>`.
+5. **Keep anchors stable**. The Sui slice uses `<module>-<item>`
+   anchors; preserve them across renames when the underlying item is
+   the same.
+
+---
+
+## Removal
+
+When a public item is removed:
+
+- Delete its `<APIItem>` block from the reference page.
+- Remove its entries from the in-page lists (Types, Functions, Events,
+  Errors).
+- Remove the matching nav entry if the entire module was removed.
+- Add a `Removed in <RELEASE_VERSION>` line under a "Version history"
+  section at the bottom of the reference page (or create the section).
+- Search the slice for stale links and either repoint them to the
+  replacement (if any) or delete them.
+
+Do not silently delete a reference page just because the file in the
+contracts repo moved. Confirm with `extract_public_api` that the item
+is actually gone.
diff --git a/skills/docs-sync/references/rules/change-classification.md b/skills/docs-sync/references/rules/change-classification.md
new file mode 100644
index 00000000..5568527d
--- /dev/null
+++ b/skills/docs-sync/references/rules/change-classification.md
@@ -0,0 +1,388 @@
+# Change classification
+
+Each contract change must be assigned exactly one **primary**
+classification. A change can also have **secondary** classifications
+when more than one row applies (e.g. a removed function that was
+security-sensitive).
+
+Classifications are deterministic. Use only the names below; the docs
+update matrix references them by exact name.
+
+For every change, record:
+
+- **File** (relative to `<CONTRACTS_REPO_PATH>`).
+- **Construct** (module / function / struct / etc.).
+- **Primary classification**.
+- **Secondary classifications** (optional, comma-separated).
+- **Evidence**: commit hash + hunk pointer.
+
+---
+
+## 1. New module/package
+
+**Detection signals**
+- A new file under the contracts library's source root, or
+- A new top-level `module <addr>::<name>;` declaration not present at
+  `<BASE_COMMIT>`.
+
+**Required evidence**
+- The file appears in `git diff --diff-filter=A`.
+- Or `extract_public_api` reports a new module name.
+
+**Documentation impact**
+- API reference page required.
+- Module overview page required (under `<VERSION_DOCS_ROOT>`).
+- Navigation entry required under both `Packages` and `API Reference`.
+- At least one usage example required.
+
+**Common false positives**
+- A file moved without API change: classify as
+  `Internal-only implementation change` if no public surface differs.
+- A test module (`*_tests.move`, `tests/...`): classify as
+  `Internal-only implementation change`.
+
+---
+
+## 2. New public function
+
+**Detection signals**
+- A `public fun ...` (or `entry fun ...`, `public(...) fun ...`) that
+  did not exist at `<BASE_COMMIT>`.
+
+**Required evidence**
+- Signature appears in `extract_public_api(<HEAD_COMMIT>)` and not in
+  `extract_public_api(<BASE_COMMIT>)`.
+
+**Documentation impact**
+- API reference entry required.
+- Guide update required if the function enables a new user task that
+  cannot be done with existing API.
+
+**Common false positives**
+- A function whose visibility was widened from private to public —
+  classify as `Changed function signature` (visibility) rather than
+  "new", because callers may already exist and migration notes change.
+- An internal helper renamed and re-exported under a public alias —
+  classify as `Changed function signature`.
+
+---
+
+## 3. Changed function signature
+
+**Detection signals**
+- Same fully qualified function path exists at both commits, but at
+  least one of: parameter list, return type, type parameters, abilities
+  bound, visibility, `entry`-ness has changed.
+
+**Required evidence**
+- Signature strings differ between `extract_public_api` outputs at the
+  two commits.
+
+**Documentation impact**
+- API reference entry required.
+- Affected guides and examples required (search by name).
+- Migration note required if the change is breaking.
+
+**Common false positives**
+- Whitespace/formatting-only changes: classify as
+  `Documentation-only source comment change` if only `///` lines moved,
+  or `Internal-only implementation change` for purely cosmetic formatting.
+- Parameter renames with no type change: still counted (they break
+  named-parameter call sites and break docs prose).
+
+---
+
+## 4. Changed behavior
+
+**Detection signals**
+- Signature unchanged, but the function body changed in a way that
+  affects observable behavior: different result for the same inputs,
+  different state mutation, different ordering of effects.
+
+**Required evidence**
+- Body diff in the function, AND at least one of:
+  - A test was updated to reflect the new behavior.
+  - Source comments / docs explicitly describe the new behavior.
+  - A new abort/event/log was introduced (see those classifications).
+
+**Documentation impact**
+- API reference required (function description).
+- Affected guides required.
+- Explanation update required if the change reflects a new mental model.
+
+**Common false positives**
+- Refactor that produces the same observable result: classify as
+  `Internal-only implementation change`.
+- Performance-only optimization with no observable change other than
+  gas/CU: classify as `Internal-only implementation change` unless
+  documented limits change.
+
+---
+
+## 5. Changed abort/error condition
+
+**Detection signals**
+- A new error constant appears (e.g. `const ENewError: u64 = ...;`) and
+  is referenced from a public function, **or**
+- A public function gains/removes/relocates an `abort` / `assert!` /
+  error-throwing call site.
+
+**Required evidence**
+- Error constant in `extract_public_api` differs.
+- `assert!`/`abort`/equivalent call sites changed in a public function.
+
+**Documentation impact**
+- API reference required (the function's `Aborts` block).
+- Affected guides and examples reviewed for misleading error claims.
+
+**Common false positives**
+- Error constant renamed but same semantic — still record (callers and
+  docs both reference the name).
+- New `assert!` purely on internal invariants impossible to trigger
+  externally: classify as `Internal-only implementation change`.
+
+---
+
+## 6. Changed event
+
+**Detection signals**
+- A new event struct (Sui: `struct ... has copy, drop` emitted via
+  `event::emit`).
+- Existing event struct gained or lost fields, or had field types
+  changed.
+- A public function added/removed an `event::emit(...)` call.
+
+**Required evidence**
+- Event struct definition differs between commits.
+- Or call-site to `event::emit` differs in a public function.
+
+**Documentation impact**
+- API reference required (the function's `Emits` block and the events
+  section).
+- Guide update required if users must observe or index the event.
+
+**Common false positives**
+- Internal logging that is not an on-chain event: classify as
+  `Internal-only implementation change`.
+
+---
+
+## 7. Changed type/struct
+
+**Detection signals**
+- A public struct/type gained or lost fields, abilities, or type
+  parameters.
+- A type alias or witness type changed.
+
+**Required evidence**
+- Struct definition differs in `extract_public_api`.
+
+**Documentation impact**
+- API reference required.
+- Examples reviewed.
+
+**Common false positives**
+- Internal struct used only by private helpers: classify as
+  `Internal-only implementation change`.
+
+---
+
+## 8. Changed ability/ownership semantics
+
+**Detection signals**
+- A struct's `has` clause changed (`key`, `store`, `copy`, `drop`).
+- A capability type was introduced, removed, or its issuance pattern
+  changed.
+- An object was made shared/owned/frozen where it was not before.
+
+**Required evidence**
+- Ability list differs in `extract_public_api`.
+- Or capability creation/transfer call sites differ in a public flow.
+
+**Documentation impact**
+- API reference required.
+- Guide review required.
+- Explanation **and** security note required (this category is almost
+  always security-relevant).
+
+**Common false positives**
+- Adding `drop` to a purely value-returning struct: still record (it
+  changes safety guarantees).
+
+---
+
+## 9. Breaking change
+
+**Detection signals** (any of):
+- A public item present at `<BASE_COMMIT>` is missing at `<HEAD_COMMIT>`.
+- A public function's parameter list, parameter type order, return
+  type, or visibility changed in a non-additive way.
+- A public struct lost fields or abilities.
+- A capability type's witness changed.
+
+**Required evidence**
+- Diff of public surface between the two commits.
+
+**Documentation impact**
+- API reference required.
+- Migration guidance required (under guides or release notes).
+- Changelog/release notes entry required.
+- This is a secondary classification: it always co-occurs with one of
+  `Removed feature`, `Changed function signature`, `Changed
+  type/struct`, or `Changed ability/ownership semantics`.
+
+**Common false positives**
+- Adding a parameter with a default-style overload (Move does not
+  natively have this — almost any signature change is breaking).
+
+---
+
+## 10. Security-sensitive behavior
+
+**Detection signals** — the change touches any of:
+- Access-control checks (admin, owner, role).
+- Capability issuance, transfer, or surrender.
+- Authorization / signature verification / replay protection.
+- Asset transfer, escrow, custody, or accounting.
+- Upgradeability hooks.
+- Cryptographic primitives (hashing, signatures, randomness).
+
+**Required evidence**
+- Diff includes one of: new/removed `assert!` on access checks, new or
+  changed capability handling, new or changed `transfer::*` paths,
+  changes to signature verification calls, or changes to crypto module
+  use.
+
+**Documentation impact**
+- Explanation or warning section required (per
+  `security.warning_style`).
+- This is a **secondary** classification — always pair with the primary
+  classification of the change.
+
+**Common false positives**
+- Renaming a private helper used by access control: still record
+  (security-sensitive even if internal-looking).
+- Adding logging around an existing check: classify as
+  `Internal-only implementation change` unless the check itself
+  changed.
+
+---
+
+## 11. Deprecated feature
+
+**Detection signals**
+- An attribute / annotation marking deprecation (`#[deprecated]` or
+  equivalent, or a `/// deprecated` doc convention).
+- A doc comment explicitly marking the item as deprecated, even without
+  a tooling-level annotation.
+
+**Required evidence**
+- Annotation or explicit doc-comment marker on the item.
+
+**Documentation impact**
+- Reference page must include a deprecation note with the deprecation
+  release and replacement.
+- Migration guidance required.
+
+**Common false positives**
+- A `// TODO: deprecate this` comment in the body is **not**
+  deprecation. Only public-facing markers count.
+
+---
+
+## 12. Removed feature
+
+**Detection signals**
+- A public item present at `<BASE_COMMIT>` is missing at `<HEAD_COMMIT>`.
+
+**Required evidence**
+- Item missing in `extract_public_api(<HEAD_COMMIT>)`.
+
+**Documentation impact**
+- Migration guidance required.
+- Release-notes entry required.
+- Existing reference content for the item should be removed; existing
+  guides that referenced it should be updated.
+
+**Common false positives**
+- Item moved to a different module or package: classify as
+  `Changed function signature` (path changed) and add `Breaking change`
+  as a secondary.
+
+---
+
+## 13. Documentation-only source comment change
+
+**Detection signals**
+- The diff for a file contains only changes to `///` doc comments or
+  `//` comments. No code tokens changed.
+
+**Required evidence**
+- Hunks contain only comment-line additions/deletions/edits.
+
+**Documentation impact**
+- API reference may need refreshed prose.
+- No code-level migration.
+
+**Common false positives**
+- A change that re-flows comments and also moves a `;` or whitespace
+  inside code: count as `Internal-only implementation change` for the
+  code part and `Documentation-only source comment change` for the
+  comment part.
+
+---
+
+## 14. Example-only change
+
+**Detection signals**
+- The diff is restricted to files under an examples / samples / fixture
+  directory inside the contracts repo (not under public sources).
+
+**Required evidence**
+- All changed paths match the contracts repo's example layout.
+
+**Documentation impact**
+- Update embedded examples in docs if the repo's examples are mirrored
+  in the docs slice.
+
+**Common false positives**
+- Test files: classify as `Internal-only implementation change`.
+
+---
+
+## 15. Internal-only implementation change
+
+**Detection signals**
+- All changes are confined to non-public modules, internal helpers,
+  tests, scripts, CI, or formatting.
+
+**Required evidence**
+- `extract_public_api(<BASE_COMMIT>) == extract_public_api(<HEAD_COMMIT>)`.
+- Or all hunks fall in directories the project marks as internal.
+
+**Documentation impact**
+- None, unless behavior, security, performance, or stated limitations
+  changed in a way users care about.
+
+**Common false positives**
+- A change that looks internal but flips a security invariant —
+  classify as `Security-sensitive behavior` (secondary) on top of the
+  primary classification.
+
+---
+
+## Multiple classifications
+
+A single hunk often produces multiple classifications:
+
+- A function signature changed in a way that breaks callers and the
+  function checks access control:
+  - Primary: `Changed function signature`
+  - Secondary: `Breaking change`, `Security-sensitive behavior`
+- A removed module that was deprecated last release:
+  - Primary: `Removed feature`
+  - Secondary: `Breaking change` (and possibly
+    `Security-sensitive behavior`)
+
+Record all secondaries — the matrix uses each classification
+independently to decide what docs to update.
diff --git a/skills/docs-sync/references/rules/config-rules.md b/skills/docs-sync/references/rules/config-rules.md
new file mode 100644
index 00000000..7b7b8e4c
--- /dev/null
+++ b/skills/docs-sync/references/rules/config-rules.md
@@ -0,0 +1,97 @@
+# docs-sync config rules
+
+The `skills/docs-sync/config/` tree is **shared memory** committed to the
+docs repo. It is the source of truth that lets every developer and every
+agent run the docs-sync process the same way.
+
+## File layout
+
+```
+skills/docs-sync/
+  config/
+    libraries/
+      <LIBRARY_ID>.yml              # one file per docs slice
+```
+
+One config file per `<LIBRARY_ID>`. If a single library has multiple
+documented versions, the active version lives in `docs.version` and any
+older or newer versions get their own config file
+(`<LIBRARY_ID>-<VERSION>.yml`) when their layout, conventions, or
+navigation differ.
+
+## Hard rules
+
+1. **Repo-relative only.** Every path inside a config file (`content_root`,
+   `library_root`, `version_root`, `api_reference_path`, `product_index_path`,
+   `version_index_path`, `local_conventions_path`, `nav_config_path`,
+   `examples_root`) is relative to `<DOCS_REPO_PATH>`. Never write absolute paths
+   (e.g. `/Users/...`, `/home/...`, `C:\\...`).
+2. **No personal local paths.** Runtime local paths
+   (`<CONTRACTS_REPO_PATH>`, `<DOCS_REPO_PATH>`) are passed as inputs at
+   call time. They are never persisted to config.
+3. **No secrets.** API keys, tokens, internal URLs, or anything sensitive
+   must not be added to config. The skill is checked into git.
+4. **Config beats inference.** When config defines a value, the agent uses
+   that value. The agent only falls back to inferring from the docs tree
+   when a field is empty or absent.
+5. **Don't silently widen scope.** Editing config to add new docs slices
+   or change `library_root` is a project-level decision. The agent must
+   call this out in the docs-sync report and, in interactive mode, ask
+   before changing it.
+
+## Reading config
+
+The agent's first concrete step on every run is:
+
+1. Resolve `<CONFIG_PATH>` (default
+   `skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`).
+2. Fail fast if the file does not exist. Do not fabricate defaults.
+3. Treat all `docs.*` paths as relative to `<DOCS_REPO_PATH>`.
+4. Validate that `library_root`, `version_root`, `api_reference_path`,
+   and `nav_config_path` exist on disk under `<DOCS_REPO_PATH>`. If any
+   is missing, stop and report it.
+
+## Updating config
+
+The agent **may** update config when, and only when, it discovers a
+durable project convention that is not yet recorded:
+
+- A new docs slice or version that the team has clearly adopted (a
+  populated `version_root`, with at least an index page and one piece of
+  reference content).
+- A navigation file that has been renamed or moved.
+- A local conventions file added at `local_conventions_path`.
+
+The agent **must not** update config to:
+
+- Reflect a one-off experiment in a feature branch.
+- Capture personal preferences (file organization, tone changes) that the
+  user has not explicitly framed as project-wide.
+- Hard-code a runtime value (e.g. a contracts repo path or a release tag).
+
+When the agent does change config, it records the change in the
+docs-sync report (`Config changes` section) with old/new values and a
+short rationale. In interactive mode it asks first.
+
+## Source-comment policy
+
+`automation.allow_source_comment_edits` controls whether the agent is
+allowed to modify source/doc comments inside `<CONTRACTS_REPO_PATH>`.
+
+- `false` (default): the agent must not edit source comments. If
+  reference content is incomplete, it generates only accurate
+  deterministic content and records a `needs-human-review` finding.
+- `true`: the agent may edit source comments **only if** the user
+  explicitly asks for it in the run prompt. Even then the agent should
+  keep edits scoped to the modules touched by the diff.
+
+## Failure handling
+
+`automation.fail_on_unresolved_placeholders` controls how the agent
+reacts to leftover placeholders in generated docs (`<TODO>`, `<FILL>`,
+`<TARGET_AUDIENCE>`, `<RELEASE_VERSION>`, etc.):
+
+- `true`: the agent stops and reports unresolved placeholders before
+  finishing.
+- `false`: the agent emits placeholders as TODOs in the report and
+  continues.
diff --git a/skills/docs-sync/references/rules/diataxis-rules.md b/skills/docs-sync/references/rules/diataxis-rules.md
new file mode 100644
index 00000000..f808693a
--- /dev/null
+++ b/skills/docs-sync/references/rules/diataxis-rules.md
@@ -0,0 +1,178 @@
+# Diátaxis rules for this docs slice
+
+This skill follows the Diátaxis framework. Each docs page belongs to
+exactly one of four categories. Mixing categories is the most common
+docs failure mode and the first thing to fix on review.
+
+## The four categories
+
+### Tutorial — *learning-oriented*
+
+A safe, linear path for a first-time user to build something and gain
+confidence. The user trusts the author to make good choices for them.
+
+- Goal: the user finishes a working artifact and understands the basic
+  shape of the library.
+- Voice: imperative, encouraging, hand-holding.
+- Scope: one path. No options, no detours.
+- Promise: every step works. The user does not have to make decisions.
+
+### How-to guide — *task-oriented*
+
+Instructions for accomplishing a specific real-world task. The user
+already knows what they want; the guide tells them how.
+
+- Goal: a concrete outcome ("transfer ownership of a wrapped object",
+  "register an indexed event", "rotate an admin capability").
+- Voice: direct, concise, problem-first.
+- Scope: one task. Optional variants belong at the bottom or in another
+  guide.
+- Promise: an experienced reader can scan and execute.
+
+### Reference — *information-oriented*
+
+Factual, complete API documentation. No teaching, no opinion, no
+narrative. Generated or maintained from source comments where possible.
+
+- Goal: the user looks up an exact signature, error, or event.
+- Voice: terse, neutral, technical.
+- Scope: every public item.
+- Promise: accurate and exhaustive.
+
+### Explanation — *understanding-oriented*
+
+Conceptual material covering rationale, tradeoffs, mental models,
+security model, and design context.
+
+- Goal: the user builds a mental model strong enough to reason about
+  edge cases the docs do not cover.
+- Voice: discursive, analytical, willing to discuss alternatives.
+- Scope: a topic, not a function.
+- Promise: explains *why*, not *how*.
+
+---
+
+## Rules to avoid mixing modes
+
+1. **Tutorials must not branch.** "Here's how to do X. Or you could do
+   Y." is a guide, not a tutorial.
+2. **Guides must not teach concepts.** If you find yourself defining
+   terms, link to an explanation page.
+3. **Reference must not editorialize.** No "this is the recommended
+   approach". Recommendations belong in guides; tradeoffs belong in
+   explanations.
+4. **Explanations must not be how-tos in disguise.** No step lists. No
+   commands to run.
+5. **Each page declares its category.** Use frontmatter or the page's
+   first sentence to make the category obvious.
+6. **One outcome per guide. One topic per explanation. One artifact per
+   tutorial.** When two outcomes belong together, split the page.
+
+---
+
+## What belongs in each (Sui examples)
+
+### Tutorial — belongs
+
+- "Build your first Sui module that uses `openzeppelin_access`
+  capabilities."
+- A linear walkthrough that ends with a working `move test`.
+
+### Tutorial — does not belong
+
+- A page comparing two ways to do access control.
+- A reference for every function in `openzeppelin_access`.
+- A discussion of when *not* to use `two_step_transfer`.
+
+### How-to guide — belongs
+
+- "Transfer ownership of a wrapped object using `two_step_transfer`."
+- "Add a new admin capability and rotate the previous one."
+- "Subscribe to `TransferAccepted` events from an off-chain indexer."
+
+### How-to guide — does not belong
+
+- A teaching introduction to capabilities.
+- A regenerated dump of every function on the module.
+- A multi-page essay about ownership theory.
+
+### Reference — belongs
+
+- The auto-generated page for `openzeppelin_access::two_step_transfer`,
+  with module summary, types, functions, events, errors.
+- Per-function entries with description, `Aborts ...`, `Emits ...`, and
+  brief NOTE/INFO/WARNING blocks.
+
+### Reference — does not belong
+
+- A walkthrough of how to use the module.
+- A "Why we built it this way" section.
+- Free-form opinion about call patterns.
+
+### Explanation — belongs
+
+- "Two-step transfer: rationale and tradeoffs vs. immediate transfer."
+- "How OpenZeppelin Contracts for Sui models capabilities."
+- "Security model of `openzeppelin_access`."
+
+### Explanation — does not belong
+
+- A function signature.
+- A literal step list.
+- A glossary entry that should live next to its first use.
+
+---
+
+## Checklist for a new docs page
+
+Use this list before writing or filing the page in `<VERSION_DOCS_ROOT>`.
+
+1. **What does the reader want when they land here?**
+   - To learn the library from zero → **Tutorial**.
+   - To get one specific job done → **How-to guide**.
+   - To look up a fact → **Reference**.
+   - To understand why → **Explanation**.
+
+2. **Will this page have a step list?**
+   - Yes, and the steps are linear and beginner-safe → Tutorial.
+   - Yes, and the steps assume the reader knows the library → How-to guide.
+   - No → Reference or Explanation.
+
+3. **Does it list every public item?**
+   - Yes → Reference.
+   - No → not Reference.
+
+4. **Does it explain *why*?**
+   - Yes, primarily → Explanation.
+   - Yes, but in service of a task → How-to guide. Move the rationale
+     to the bottom or link out.
+
+5. **Where does it live?**
+   - Tutorial → `<VERSION_DOCS_ROOT>/learn/`.
+   - How-to guide → `<VERSION_DOCS_ROOT>/<package>.mdx` (package
+     overview pages function as guides) or its own task page.
+   - Reference → `<API_REFERENCE_PATH>/<package>.mdx`.
+   - Explanation → `<VERSION_DOCS_ROOT>/<package>.mdx` rationale section
+     for short pieces, or a dedicated page for substantial topics.
+
+6. **Was the category obvious from the first paragraph?** If not,
+   rewrite the first paragraph until it is.
+
+---
+
+## Refactoring rules
+
+When updating an existing page, fix mode-mixing as you go, but only
+within scope of the change set:
+
+- A reference page that contains a tutorial-style preamble: keep the
+  preamble in the same edit only if you are also editing that section
+  for accuracy. Otherwise leave a `needs-human-review` finding in the
+  report and move on.
+- A tutorial that branches into options: file a `needs-human-review`
+  finding rather than rewriting opportunistically.
+- An explanation that has drifted into how-to: same — flag, don't
+  rewrite outside the change set.
+
+The `docs-sync` run is not a refactor pass. The goal is to keep docs
+truthful relative to the contracts diff, not to rewrite the slice.
diff --git a/skills/docs-sync/references/rules/doc-update-matrix.md b/skills/docs-sync/references/rules/doc-update-matrix.md
new file mode 100644
index 00000000..e663861b
--- /dev/null
+++ b/skills/docs-sync/references/rules/doc-update-matrix.md
@@ -0,0 +1,277 @@
+# Doc update matrix
+
+Maps every change classification (from `references/rules/change-classification.md`) to
+the docs surfaces that must be updated.
+
+Columns:
+
+- **Change type** — primary or secondary classification name.
+- **API ref** — must update API reference?
+- **Guide** — must update or create a how-to guide?
+- **Tutorial** — must update or create a tutorial?
+- **Explanation** — must update or create an explanation page?
+- **Example** — must update or create code examples?
+- **Nav** — must update navigation (`<NAV_CONFIG_PATH>`)?
+- **Release notes** — must add a changelog / release-notes entry?
+- **Security warning** — must add or update an explicit warning callout?
+- **Auto mode** — what automatic mode does without asking.
+- **Interactive prompts** — focused questions to ask, only if the
+  answer changes scope/audience/examples/release notes/security
+  framing.
+
+Cells use:
+
+- `YES` — the agent must do it.
+- `IF NEW TASK` — required only when the change enables a user task
+  that did not exist before.
+- `REVIEW` — read the relevant pages, edit only if they would now be
+  wrong.
+- `OPT` — optional; defer unless the matrix or local conventions force
+  it.
+- `NO` — do not edit.
+
+> When multiple rows apply (a change with secondary classifications),
+> the **union** of `YES`/`REVIEW`/`IF NEW TASK` cells across rows
+> applies. `NO` is overridden by any other value.
+
+---
+
+## 1. New module/package
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | IF NEW TASK |
+| Tutorial | OPT |
+| Explanation | OPT |
+| Example | YES (at least one usage example) |
+| Nav | YES (Packages folder + API Reference folder) |
+| Release notes | YES |
+| Security warning | REVIEW (apply if topic in `security.require_security_sections_for`) |
+| Auto mode | Generate API ref page + minimal package overview page from source comments and templates. Add nav entries. Insert a stub example using existing snippet style. |
+| Interactive prompts | "Is this module aimed at <TARGET_AUDIENCE>, or a different audience?" • "Is there a concrete user task this enables that needs a how-to guide?" • "Should we draft an explanation page for the design, or is the package overview enough?" |
+
+## 2. New public function
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | IF NEW TASK |
+| Tutorial | OPT |
+| Explanation | OPT |
+| Example | REVIEW (add a snippet under the function entry) |
+| Nav | NO (unless the new function lives in a brand-new module) |
+| Release notes | YES |
+| Security warning | REVIEW |
+| Auto mode | Insert function entry into the appropriate API reference page in canonical order. Update example snippets if the surrounding module already has them. |
+| Interactive prompts | "Does this function enable a new user task that should be its own how-to guide?" • "Are there security caveats users must see?" |
+
+## 3. Changed function signature
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | YES (every guide that names the function) |
+| Tutorial | REVIEW |
+| Explanation | REVIEW |
+| Example | YES (every example that calls the function) |
+| Nav | NO (unless the path moved) |
+| Release notes | YES (with migration note if breaking) |
+| Security warning | REVIEW |
+| Auto mode | Replace signature in API reference. Update every snippet that uses the function. Add migration note if `Breaking change` is a secondary. |
+| Interactive prompts | "Should the migration note include a code-level before/after, or is a one-line note enough?" |
+
+## 4. Changed behavior
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | YES |
+| Tutorial | REVIEW |
+| Explanation | REVIEW |
+| Example | REVIEW |
+| Nav | NO |
+| Release notes | YES |
+| Security warning | REVIEW |
+| Auto mode | Update function description in API reference. Update guides that reference the prior behavior. |
+| Interactive prompts | "Does the new behavior change the recommended pattern in any tutorial or explanation?" |
+
+## 5. Changed abort/error condition
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | REVIEW |
+| Tutorial | REVIEW |
+| Explanation | NO |
+| Example | REVIEW |
+| Nav | NO |
+| Release notes | OPT (YES if user-observable) |
+| Security warning | REVIEW |
+| Auto mode | Regenerate the function's `Aborts` block from source. Search guides for the error name and review references. |
+| Interactive prompts | "Is the new abort condition something integrators commonly hit, or an internal invariant?" |
+
+## 6. Changed event
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | YES if users must observe / index it |
+| Tutorial | REVIEW |
+| Explanation | OPT |
+| Example | REVIEW (event handling snippet) |
+| Nav | NO |
+| Release notes | YES |
+| Security warning | REVIEW |
+| Auto mode | Update events section and the emitting function's `Emits` block. Update indexer/observer snippet if one exists. |
+| Interactive prompts | "Should integrators be told to subscribe to this event in a how-to guide?" |
+
+## 7. Changed type/struct
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | REVIEW |
+| Tutorial | REVIEW |
+| Explanation | OPT |
+| Example | REVIEW |
+| Nav | NO |
+| Release notes | YES if breaking |
+| Security warning | REVIEW |
+| Auto mode | Replace the struct definition in API reference. Update field documentation. |
+| Interactive prompts | "Did the field semantics change for users, or is this a rename only?" |
+
+## 8. Changed ability/ownership semantics
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | YES |
+| Tutorial | REVIEW |
+| Explanation | YES |
+| Example | REVIEW |
+| Nav | NO |
+| Release notes | YES |
+| Security warning | YES |
+| Auto mode | Update API reference; add or refresh an explanation note covering the new ownership/ability model; add a security warning callout. Do not delete prior explanation prose without confirmation. |
+| Interactive prompts | "Does this change the recommended custody pattern?" • "Does it affect upgrade migration?" |
+
+## 9. Breaking change
+
+| Field | Value |
+|---|---|
+| API ref | YES |
+| Guide | YES |
+| Tutorial | REVIEW |
+| Explanation | REVIEW |
+| Example | YES |
+| Nav | REVIEW |
+| Release notes | YES (migration section required) |
+| Security warning | REVIEW |
+| Auto mode | Add a migration section under release notes; do not delete pre-break content unless the corresponding API was removed. |
+| Interactive prompts | "Should we publish a stand-alone migration guide, or fold the migration into the release notes?" |
+
+## 10. Security-sensitive behavior
+
+| Field | Value |
+|---|---|
+| API ref | YES (security note in the relevant function/module) |
+| Guide | REVIEW |
+| Tutorial | REVIEW |
+| Explanation | YES |
+| Example | REVIEW |
+| Nav | NO |
+| Release notes | YES |
+| Security warning | YES |
+| Auto mode | Apply `security.warning_style` callout in the affected reference entries; ensure an explanation page exists for the topic and link both ways. |
+| Interactive prompts | "Should this be a top-level security advisory in release notes?" |
+
+## 11. Deprecated feature
+
+| Field | Value |
+|---|---|
+| API ref | YES (deprecation note + replacement) |
+| Guide | REVIEW |
+| Tutorial | REVIEW |
+| Explanation | REVIEW |
+| Example | REVIEW (replace usage with replacement) |
+| Nav | NO |
+| Release notes | YES |
+| Security warning | REVIEW |
+| Auto mode | Add `Deprecated in <RELEASE_VERSION>` block to the reference entry; suggest replacement. Add migration note. Do not delete the entry. |
+| Interactive prompts | "Should existing examples switch to the replacement now, or stay on the deprecated API until removal?" |
+
+## 12. Removed feature
+
+| Field | Value |
+|---|---|
+| API ref | YES (delete entry; add removal note in version history) |
+| Guide | YES (remove or rewrite usage; add migration) |
+| Tutorial | REVIEW |
+| Explanation | REVIEW |
+| Example | YES (replace or delete) |
+| Nav | YES (remove dead nav entries) |
+| Release notes | YES (Removed section) |
+| Security warning | REVIEW |
+| Auto mode | Remove the API reference entry, the nav entry, and stale references. Preserve a "Removed in <RELEASE_VERSION>" line in the version-history section. |
+| Interactive prompts | "Was this removal intentional and final, or temporarily reverted?" |
+
+## 13. Documentation-only source comment change
+
+| Field | Value |
+|---|---|
+| API ref | REVIEW (refresh prose if it diverges from new comments) |
+| Guide | NO |
+| Tutorial | NO |
+| Explanation | NO |
+| Example | NO |
+| Nav | NO |
+| Release notes | NO |
+| Security warning | NO |
+| Auto mode | Refresh API reference prose only. Skip if the new comment is purely cosmetic. |
+| Interactive prompts | (none — too low-impact to interrupt) |
+
+## 14. Example-only change
+
+| Field | Value |
+|---|---|
+| API ref | NO |
+| Guide | REVIEW |
+| Tutorial | REVIEW |
+| Explanation | NO |
+| Example | YES |
+| Nav | NO |
+| Release notes | OPT |
+| Security warning | NO |
+| Auto mode | Mirror example changes into the docs slice's embedded examples or `examples_root`. |
+| Interactive prompts | (none) |
+
+## 15. Internal-only implementation change
+
+| Field | Value |
+|---|---|
+| API ref | NO |
+| Guide | NO |
+| Tutorial | NO |
+| Explanation | NO |
+| Example | NO |
+| Nav | NO |
+| Release notes | NO (unless behavior, security, performance, or limitations changed) |
+| Security warning | NO |
+| Auto mode | No-op. Record in report. |
+| Interactive prompts | (none) |
+
+---
+
+## Aggregation rules
+
+When the same docs page is touched by multiple change classifications:
+
+1. Take the union of required updates.
+2. Apply API reference updates first (deterministic).
+3. Then apply guide / tutorial / explanation updates, in that order.
+4. Then update examples.
+5. Then update navigation.
+6. Then update release notes.
+
+Each docs page is edited at most once per run.
diff --git a/skills/docs-sync/references/rules/docs-pr-checklist.md b/skills/docs-sync/references/rules/docs-pr-checklist.md
new file mode 100644
index 00000000..77fbdd05
--- /dev/null
+++ b/skills/docs-sync/references/rules/docs-pr-checklist.md
@@ -0,0 +1,139 @@
+# docs PR checklist
+
+The agent must walk through this list at the end of every run, mark
+each item pass / fail / N/A, and surface the result in the docs-sync
+report. Do not skip items. If any item is `fail`, the run is **not
+done** — either fix it (interactive: confirm with user; automatic:
+within configured rules) or surface it explicitly.
+
+---
+
+## 1. API reference
+
+- [ ] Every changed public item has an updated entry in
+  `<API_REFERENCE_PATH>`.
+- [ ] Every newly added public item has a new entry, in the canonical
+  source order.
+- [ ] Every removed public item has been removed from the reference
+  page **and** from the in-page lists (Types, Functions, Events,
+  Errors, Constants).
+- [ ] Source links (`APIGithubLinkHeader` for Sui) point to
+  `<RELEASE_VERSION>` (or `<HEAD_COMMIT>` if no tag exists), not to
+  `main`.
+- [ ] Function entries follow the canonical entry order from
+  `<LOCAL_DOCS_CONVENTIONS_PATH>` (for Sui: description → Aborts →
+  Emits → NOTE/INFO/WARNING).
+- [ ] Anchors are stable for items that were not renamed.
+
+## 2. Guides
+
+- [ ] Every guide whose subject overlaps the change set has been
+  reviewed.
+- [ ] Stale signatures, parameter lists, error names, and event names
+  are gone.
+- [ ] New guides for `New module/package` and applicable `IF NEW TASK`
+  rows in `references/rules/doc-update-matrix.md` have been created and
+  follow `references/templates/guide-template.md`.
+
+## 3. Tutorials
+
+- [ ] Tutorials whose ending state depends on the changed API still
+  produce the documented final result.
+- [ ] No tutorial has gained a branch ("Option A or Option B") as a
+  result of the change.
+- [ ] Tutorial code snippets parse with the new API.
+
+## 4. Explanations
+
+- [ ] Explanation pages flagged by the matrix have been reviewed.
+- [ ] No new how-to-style step lists were introduced into explanation
+  pages.
+- [ ] Security-sensitive design changes have an updated explanation.
+
+## 5. Examples
+
+- [ ] Embedded code snippets parse / compile per
+  `examples.snippet_validation` (or `examples.compile_command` if set).
+- [ ] No example uses a removed function, struct, error, or event.
+- [ ] No example uses an outdated package address or module path.
+
+## 6. Links
+
+- [ ] Internal links inside the slice resolve to existing pages.
+- [ ] Anchors inside the slice resolve to existing ids.
+- [ ] No `#TODO`, `<TODO>`, or template `<PLACEHOLDER>` tokens remain
+  unless `automation.fail_on_unresolved_placeholders: false`.
+
+## 7. Navigation
+
+- [ ] `<NAV_CONFIG_PATH>` lists every page reachable in the slice.
+- [ ] `<NAV_CONFIG_PATH>` no longer references deleted pages.
+- [ ] Folder structure matches `navigation.required_folders` if
+  configured.
+- [ ] No `meta.json` files were created or edited (per
+  `navigation.forbid_meta_json: true`).
+
+## 8. Changelog / release notes
+
+- [ ] `Breaking change`, `Removed feature`, `Deprecated feature`, and
+  user-observable behavior changes are reflected in release notes when
+  this docs slice has an established release-notes location; otherwise
+  the report lists the missing release-notes destination.
+- [ ] Migration notes appear under the relevant guide or release-notes
+  section for breaking changes.
+
+## 9. Stale identifiers
+
+- [ ] No removed function names appear in prose, headings, or links.
+- [ ] No old package ids, addresses, or module paths appear.
+- [ ] No old function signatures appear in code blocks or prose.
+- [ ] No old event or error names appear in prose unless explicitly
+  preserved as historical references in a "Version history" section.
+
+## 10. Placeholders
+
+- [ ] No `<TODO>`, `<FILL>`, `<TARGET_AUDIENCE>`, `<RELEASE_VERSION>`,
+  `<…>` placeholders remain.
+- [ ] If `automation.fail_on_unresolved_placeholders: true` and any
+  remain, the run reports `fail` for this item and lists every
+  unresolved placeholder by file and line.
+
+## 11. Security-sensitive changes
+
+- [ ] Every change classified `Security-sensitive behavior` has an
+  explicit warning callout (per `security.warning_style`) in the
+  affected reference entries.
+- [ ] If the topic is in `security.require_security_sections_for`, the
+  matching guide and explanation pages have a security section.
+- [ ] Security warnings are factual and specific (no vague "be
+  careful").
+
+## 12. Breaking changes
+
+- [ ] Every change classified `Breaking change` has either a migration
+  section in the release notes, or a migration paragraph in the
+  primary guide for the affected feature.
+- [ ] Migration text shows before/after at code level if the matrix
+  flagged "code-level before/after" in interactive mode (or by default
+  in automatic mode for non-trivial signatures).
+
+## 13. Assumptions recorded
+
+- [ ] Every assumption made during the run is in the report's
+  `Assumptions` section.
+- [ ] Every unresolved TODO is in the report's `Unresolved TODOs`
+  section, with file, line, and reason.
+
+## 14. Scope of edits
+
+- [ ] All edits are inside `<LIBRARY_DOCS_ROOT>` (recursively),
+  `<NAV_CONFIG_PATH>`, or shared example files explicitly required by
+  the matrix.
+- [ ] No other docs slice (e.g. `content/contracts-cairo/`,
+  `content/contracts-stylus/`) was touched.
+- [ ] No source comments in `<CONTRACTS_REPO_PATH>` were edited unless
+  `automation.allow_source_comment_edits: true` **and** the user
+  authorized it.
+- [ ] No `meta.json` files were created or edited.
+- [ ] No personal local filesystem paths appear anywhere in the
+  generated content.
diff --git a/skills/docs-sync/references/templates/api-reference-template.md b/skills/docs-sync/references/templates/api-reference-template.md
new file mode 100644
index 00000000..79689d10
--- /dev/null
+++ b/skills/docs-sync/references/templates/api-reference-template.md
@@ -0,0 +1,186 @@
+# API reference template
+
+Use this template when creating or refreshing an API reference page.
+The page is generated from source comments and structured data; only
+the prose carried over from existing pages is edited by hand.
+
+This template assumes the slice's
+`api_reference_layout.page_per: package` setting (one MDX file per
+package, modules as sections inside). If a slice uses one page per
+module, drop the per-module wrapper and apply the same internal
+structure.
+
+---
+
+```mdx
+---
+title: <Package> API Reference
+---
+
+import { APIItem, APIGithubLinkHeader } from "@/components/api"
+
+This page documents the public API of `<package_name>` for
+<LIBRARY_HUMAN_NAME> `<RELEASE_VERSION>`.
+
+### `<module_name>` [toc] [#<module_name>]
+
+<APIGithubLinkHeader
+  moduleName="<module_name>"
+  link="<source_repo_url>/blob/<RELEASE_VERSION>/<source_path>"
+/>
+
+```move
+use <package>::<module_name>;
+```
+
+<One-paragraph module summary, carried over from source `///`
+comments.>
+
+<Optional: a second short paragraph with the module's key invariants
+or usage constraints. Keep it factual.>
+
+Types
+
+- [`<TypeName>`](#<module_name>-<TypeName>)
+
+Functions
+
+- [`<function_name>(<args>)`](#<module_name>-<function_name>)
+
+Events
+
+- [`<EventName>`](#<module_name>-<EventName>)
+
+Errors
+
+- [`<EErrorName>`](#<module_name>-<EErrorName>)
+
+Constants
+
+- [`<CONSTANT_NAME>`](#<module_name>-<CONSTANT_NAME>)
+
+#### Types [!toc] [#<module_name>-Types]
+
+<APIItem
+  functionSignature="struct <TypeName><T: key + store>"
+  id="<module_name>-<TypeName>"
+  kind="struct"
+>
+<One-paragraph description.>
+
+<Optional: per-field bullet list when fields are not self-explanatory.>
+
+- `field_a: T` — <one-line description>.
+- `field_b: u64` — <one-line description>.
+
+<Optional: ability/ownership note, when non-obvious.>
+</APIItem>
+
+#### Constants [!toc] [#<module_name>-Constants]
+
+<APIItem
+  functionSignature="const <CONSTANT_NAME>: u64 = <value>;"
+  id="<module_name>-<CONSTANT_NAME>"
+  kind="const"
+>
+<One-line description.>
+</APIItem>
+
+#### Functions [!toc] [#<module_name>-Functions]
+
+<APIItem
+  functionSignature="public fun <function_name><T>(arg: &T, ctx: &mut TxContext): <ReturnType>"
+  id="<module_name>-<function_name>"
+  kind="function"
+>
+<Description paragraph(s) — what the function does.>
+
+Aborts with `<EErrorName>` if `<condition>`.
+Aborts with `<EOtherError>` if `<condition>`.
+
+Emits `<EventName>` on `<when>`.
+
+> **NOTE**: <only if needed; brief>.
+> **WARNING**: <only if needed; brief>.
+
+<Optional: one minimal example. Keep it small.>
+
+```move
+let result = <module_name>::<function_name>(&obj, ctx);
+```
+</APIItem>
+
+#### Events [!toc] [#<module_name>-Events]
+
+<APIItem
+  functionSignature="public struct <EventName> has copy, drop"
+  id="<module_name>-<EventName>"
+  kind="event"
+>
+<One-paragraph description of when this event is emitted.>
+
+- `field_a: ID` — <one-line description>.
+- `field_b: address` — <one-line description>.
+</APIItem>
+
+#### Errors [!toc] [#<module_name>-Errors]
+
+<APIItem
+  functionSignature="const <EErrorName>: u64 = <code>;"
+  id="<module_name>-<EErrorName>"
+  kind="error"
+>
+<One-line condition that triggers this error.>
+</APIItem>
+
+---
+
+## Type parameters
+
+<If the module's exported items use type parameters with
+non-obvious constraints, document them once at the module level
+rather than repeating per item. Example:>
+
+- `T: key + store` — the wrapped object type. Must be `key` so it can
+  be transferred and `store` so it can be put inside another object.
+
+## Abilities and ownership
+
+<If the module establishes a non-trivial ownership pattern (e.g.
+shared object with capability-gated mutation, or wrapped object with
+constrained transfer), summarize it here.>
+
+## Security notes
+
+<Apply `security.warning_style` from config. Cross-link to the
+matching explanation page when one exists.>
+
+## Version history
+
+- **<RELEASE_VERSION>**: <added / changed / removed items, one bullet
+  each>.
+- **<previous version>**: <…>.
+```
+
+---
+
+## Authoring rules
+
+- **Source order, not alphabetical**, for sections within a module.
+  Source order is meaningful in Move and matches the contracts repo.
+- **Carry over working prose verbatim.** Do not rewrite for style.
+  Replace prose only when it has become wrong.
+- **Match canonical entry order** (description → Aborts → Emits →
+  NOTE/INFO/WARNING) per `<LOCAL_DOCS_CONVENTIONS_PATH>`. For Sui this
+  order is mandatory.
+- **Stable anchors.** Use `<module>-<item>` ids. Do not change them on
+  rename if the item is the same; add a redirect entry instead.
+- **Source links pinned to `<RELEASE_VERSION>`** when one exists,
+  otherwise to `<HEAD_COMMIT>`.
+
+## Where to put the file
+
+- File: `<API_REFERENCE_PATH>/<package>.mdx` for `page_per: package`.
+- File: `<API_REFERENCE_PATH>/<package>/<module>.mdx` for
+  `page_per: module`.
+- Nav entry: under the `API Reference` folder in `<NAV_CONFIG_PATH>`.
diff --git a/skills/docs-sync/references/templates/explanation-template.md b/skills/docs-sync/references/templates/explanation-template.md
new file mode 100644
index 00000000..99248c5a
--- /dev/null
+++ b/skills/docs-sync/references/templates/explanation-template.md
@@ -0,0 +1,127 @@
+# Explanation template
+
+Use this template when creating or rewriting an explanation page. An
+explanation is **understanding-oriented**: it builds the reader's
+mental model, covers rationale, tradeoffs, security model, and
+integration context.
+
+An explanation does **not** teach a workflow (use a tutorial), does
+**not** prescribe a recipe (use a how-to guide), and does **not** list
+function signatures (use the reference).
+
+---
+
+```mdx
+---
+title: <Topic, e.g. "Two-step ownership transfer: model and tradeoffs">
+description: <One sentence framing the topic.>
+---
+
+# <Title>
+
+## Problem
+
+<One or two paragraphs framing the problem this design exists to
+solve. State it from the user's perspective. Why would a developer
+care? What goes wrong if the problem is ignored?>
+
+## Mental model
+
+<The model we want the reader to internalize. Diagrams or simple text
+sketches are encouraged. Define the actors, the objects, and the
+invariants in 3–6 short paragraphs.>
+
+- **Actors**: <who initiates / approves / observes / cancels?>
+- **Objects**: <what state lives where?>
+- **Invariants**: <what is always true while a flow is in progress?>
+
+## Design rationale
+
+<Why is the system shaped this way? Walk through the constraints that
+forced the design:
+
+- Move language constraints (abilities, ownership, type system).
+- Sui object model constraints (owned vs shared, transfer rules).
+- Security constraints (least privilege, replay protection,
+  recoverability).
+- Operational constraints (PTB composability, gas, indexing).>
+
+## Alternatives considered
+
+<2–4 alternatives that were considered and rejected, each with one
+paragraph on why. This is the section that pays the most readers per
+line written — most users land on explanations to confirm or
+challenge their own design instincts.>
+
+- **Alternative A — <name>.** Pros: <…>. Cons: <…>. Reason rejected: <…>.
+- **Alternative B — <name>.** Pros: <…>. Cons: <…>. Reason rejected: <…>.
+- **Alternative C — <name>.** Pros: <…>. Cons: <…>. Reason rejected: <…>.
+
+## Tradeoffs
+
+<What does the chosen design give up? Be honest. If the design has a
+worse worst case than an alternative, say so.>
+
+- <Tradeoff: extra round-trip / extra object / more events.>
+- <Tradeoff: different failure mode that integrators must handle.>
+- <Tradeoff: stricter prerequisites for integrators.>
+
+## Security implications
+
+<Apply `security.warning_style` from config. Cover, in order:>
+
+1. **Trust assumptions** — who must be honest for the design to hold?
+2. **Authority model** — who can do what at each stage?
+3. **Failure modes** — what can go wrong, and what happens when it does?
+4. **Recoverability** — how do users undo a mistake?
+5. **Replay / griefing / denial-of-service** — how is it prevented?
+
+If this topic is in `security.require_security_sections_for`, expand
+this section in detail. Use explicit `WARNING` callouts for
+self-inflicted footguns.
+
+## Integration notes
+
+<How does this design interact with the rest of the library, with
+PTBs, with off-chain indexers, with upgrade paths?>
+
+- **Composability**: <PTB-friendly? Hot-potato patterns? `entry`
+  vs `public`?>
+- **Indexing**: <which events should off-chain consumers subscribe to?>
+- **Upgrade considerations**: <what stays stable across module
+  upgrades, what doesn't?>
+- **Cross-package interactions**: <known interactions with other
+  OpenZeppelin Contracts for Sui packages.>
+
+## Related guides
+
+- [<task that uses this design>](../<package>.mdx)
+- [<another task>](../<package>.mdx)
+
+## Related API reference
+
+- [`<module>`](../api/<package>.mdx#<package>-<module>)
+- [`<function>`](../api/<package>.mdx#<package>-<module>-<function>)
+```
+
+---
+
+## Authoring rules
+
+- **No step lists.** If the page would benefit from a step list, the
+  content belongs in a how-to guide.
+- **No exhaustive function listings.** That belongs in reference. If
+  you mention a function, link to it instead of redocumenting it.
+- **State opinions clearly.** Explanations are the one place where the
+  docs may say "we recommend X over Y, because Z".
+- **Match `docs.tone` from config.** Default: *clear, precise,
+  security-conscious*. In explanations this means: willing to discuss
+  what could go wrong and willing to compare to alternatives.
+
+## Where to put the file
+
+- File: `<VERSION_DOCS_ROOT>/<package>.mdx` for short rationale
+  attached to a package overview, or
+  `<VERSION_DOCS_ROOT>/<topic>.mdx` for a stand-alone explanation.
+- Nav entry: under the `Packages` folder in `<NAV_CONFIG_PATH>`, or a
+  dedicated "Concepts" / "Explanations" folder if the slice has one.
diff --git a/skills/docs-sync/references/templates/guide-template.md b/skills/docs-sync/references/templates/guide-template.md
new file mode 100644
index 00000000..aafb25a8
--- /dev/null
+++ b/skills/docs-sync/references/templates/guide-template.md
@@ -0,0 +1,147 @@
+# How-to guide template
+
+Use this template when creating or rewriting a how-to guide. A how-to
+guide is **task-oriented**: the reader has a concrete outcome in mind
+and wants the shortest reliable path to it.
+
+If the reader is learning the library for the first time, use
+`tutorial-template.md` instead. If the reader is looking up a fact, use
+`api-reference-template.md`. If the reader wants to understand *why*,
+use `explanation-template.md`.
+
+---
+
+```mdx
+---
+title: <Action verb + object> (e.g. "Rotate an admin capability")
+description: <One sentence describing the user goal.>
+---
+
+import { APIItem, APIGithubLinkHeader } from "@/components/api"
+
+# <Title>
+
+## Goal
+
+<One short paragraph: what the reader will have done by the end of this
+guide. Phrase it as the user's outcome, not the library's behavior.>
+
+## Prerequisites
+
+- <Library and version, e.g. `openzeppelin_access` v1.x.>
+- <Sui CLI / toolchain version, if relevant.>
+- <Any setup the reader needs, with links to install steps — do not
+  reproduce them here.>
+- <Familiarity assumed — link to explanations or tutorials, never
+  re-teach.>
+
+## When to use this
+
+<2–4 bullets describing situations where this guide applies, and
+*explicitly* situations where another guide or pattern is better.>
+
+- Use when: <…>
+- Use when: <…>
+- Do **not** use when: <… — link to the alternative.>
+
+## Minimal example
+
+A self-contained snippet that performs the task with the smallest
+reasonable inputs. The reader should be able to copy this, change the
+inputs, and have a working result.
+
+```move
+// Minimal example: <one-line description>.
+module my_app::example;
+
+use openzeppelin_access::two_step_transfer;
+
+public fun example(/* … */) {
+    // <smallest sequence of calls>
+}
+```
+
+## Step-by-step
+
+Numbered steps, each with:
+
+- A one-sentence imperative ("Wrap the object").
+- A code block showing the call.
+- A short note on what happened, only if non-obvious.
+
+1. <Step name>
+   ```move
+   <code>
+   ```
+2. <Step name>
+   ```move
+   <code>
+   ```
+3. <Step name>
+   ```move
+   <code>
+   ```
+
+## Security considerations
+
+<Apply `security.warning_style` from config. Use explicit warning
+callouts where the user can footgun themselves. Be specific:>
+
+> **WARNING**: <exact failure mode> happens if <exact condition>.
+
+If the topic is in `security.require_security_sections_for`, this
+section is **required** and must list:
+
+- Who holds authority at each step.
+- What an attacker can and cannot do at each step.
+- The minimum invariants the user must preserve.
+
+## Common mistakes
+
+- <Mistake → why it fails → fix.>
+- <Mistake → why it fails → fix.>
+- <Mistake → why it fails → fix.>
+
+## Full example
+
+A complete, self-contained module or scenario the reader can drop into
+their project. Larger than the minimal example; closer to production
+shape.
+
+```move
+// Full example: <one-line description>.
+module my_app::full_example;
+
+// imports
+
+// types
+
+// functions
+
+// tests (optional)
+```
+
+## Related API reference
+
+- [`<module_a>`](../api/<package>.mdx#<package>-<module_a>)
+- [`<function_b>`](../api/<package>.mdx#<package>-<module_a>-<function_b>)
+
+## Version notes
+
+- **Available since**: <RELEASE_VERSION>.
+- **Last verified against**: <RELEASE_VERSION>.
+- **Breaking changes**: <if any, link to migration section>.
+```
+
+---
+
+## Authoring rules
+
+- Keep it task-shaped. If you find yourself defining concepts, link to
+  an explanation page.
+- Do not branch in the step-by-step section. If two paths are equally
+  valid, write two guides.
+- Do not include narrative context that does not advance the task. The
+  reader is busy.
+- Match `docs.tone` from config. Default for the contracts-sui slice:
+  *clear, precise, security-conscious*.
diff --git a/skills/docs-sync/references/templates/tutorial-template.md b/skills/docs-sync/references/templates/tutorial-template.md
new file mode 100644
index 00000000..8caf4451
--- /dev/null
+++ b/skills/docs-sync/references/templates/tutorial-template.md
@@ -0,0 +1,145 @@
+# Tutorial template
+
+Use this template when creating or rewriting a tutorial. A tutorial is
+**learning-oriented**: a first-time user follows a single safe linear
+path and ends with a working artifact.
+
+A tutorial does **not** branch, does **not** present alternatives, and
+does **not** explain the design. Save those for explanations and
+how-to guides.
+
+---
+
+```mdx
+---
+title: <Imperative + outcome> (e.g. "Build your first wrapped object")
+description: <One sentence: what the reader will build.>
+---
+
+# <Title>
+
+## What you'll learn
+
+<One short paragraph stating the learning goal in concrete terms. Not
+"You will understand capabilities." Instead: "You will build a Sui
+module that mints, wraps, and transfers an object using
+`openzeppelin_access::two_step_transfer`, and run its tests
+successfully.">
+
+## What you'll build
+
+<A specific, observable artifact: a module, a working test suite, a
+runnable script, etc. Include the final file structure if helpful.>
+
+```
+my_first_oz/
+├── Move.toml
+└── sources/
+    ├── my_first_oz.move
+    └── my_first_oz_tests.move
+```
+
+## Prerequisites
+
+- <Toolchain — exact versions.>
+- <Optional: a quick check command the reader can run to confirm setup.>
+- <Reading: only one or two links, and only when truly required.>
+
+## Starting point
+
+<Provide the exact starting state. Either:
+- a `git clone` of a starter branch in the docs repo's examples, or
+- the literal contents of every starter file inline.>
+
+```toml
+# Move.toml — starter
+[package]
+name = "my_first_oz"
+edition = "2024"
+```
+
+```move
+// sources/my_first_oz.move — starter
+module my_first_oz::my_first_oz;
+```
+
+## Step 1 — <verb + object>
+
+<One short paragraph framing the step. What are we doing and why does
+it move us forward? The reader does not need to understand "why"
+deeply — they need to know that this step is intentional.>
+
+```move
+<exact code the reader pastes>
+```
+
+**Checkpoint**: <a one-line check the reader runs to confirm progress
+— e.g. `sui move build` succeeds, or a specific test passes.>
+
+## Step 2 — <verb + object>
+
+<…>
+
+```move
+<…>
+```
+
+**Checkpoint**: <…>
+
+## Step 3 — <verb + object>
+
+<…>
+
+```move
+<…>
+```
+
+**Checkpoint**: <…>
+
+## Expected result
+
+<Show the final state the reader should now have:
+- the final file contents (or a diff from start),
+- the output of running tests,
+- any explorer / CLI command outputs that confirm success.>
+
+```
+$ sui move test
+…
+PASS    [ 0 ] my_first_oz::my_first_oz_tests::happy_path
+```
+
+## Cleanup or next steps
+
+- <One-line cleanup if the tutorial used disposable resources.>
+- <Where to go next: pointer to one or two how-to guides for adjacent
+  tasks.>
+
+## Related reference and explanation
+
+- Reference: [`<package>` API](../api/<package>.mdx)
+- Explanation: [<topic explanation>](./<explanation-page>.mdx)
+- More guides: [<guide title>](./<guide>.mdx)
+```
+
+---
+
+## Authoring rules
+
+- **One path.** No "Option A or Option B" branches. If alternatives
+  matter, write a separate guide.
+- **Every step works.** If a step depends on platform behavior that
+  differs by OS, document it inline; do not silently drop the reader
+  into a difference.
+- **No design discussion.** Save it for an explanation. The reader is
+  not ready to evaluate tradeoffs yet.
+- **Checkpoints earn trust.** Every 1–3 steps, give the reader a way to
+  confirm they are still on the rails.
+- **Match `docs.tone` from config.** Default: *clear, precise,
+  security-conscious*. In tutorials this means: encouraging, but with
+  honest security warnings inline rather than postponed.
+
+## Where to put the file
+
+- File: `<VERSION_DOCS_ROOT>/learn/<kebab-case-title>.mdx`.
+- Nav entry: under the `Learn` folder in `<NAV_CONFIG_PATH>`.

From 65a101d0a301a05b876a4f288cf2acc18ec77225 Mon Sep 17 00:00:00 2001
From: Eric Nordelo <eric.nordelo39@gmail.com>
Date: Wed, 29 Apr 2026 14:54:56 +0200
Subject: [PATCH 2/5] feat: add release-v1.1 of sui diff

---
 content/contracts-sui/1.x/api/access.mdx      |    4 +-
 content/contracts-sui/1.x/api/fixed-point.mdx | 1119 +++++++++++++++++
 content/contracts-sui/1.x/api/math.mdx        |   67 +-
 content/contracts-sui/1.x/fixed-point.mdx     |  116 ++
 .../1.x/learn/access-walkthrough.mdx          |    4 +-
 content/contracts-sui/1.x/math.mdx            |    7 +-
 skills/docs-sync/SKILL.md                     |   31 +-
 skills/docs-sync/process.md                   |   86 ++
 src/navigation/sui/current.json               |   10 +
 9 files changed, 1413 insertions(+), 31 deletions(-)
 create mode 100644 content/contracts-sui/1.x/api/fixed-point.mdx
 create mode 100644 content/contracts-sui/1.x/fixed-point.mdx

diff --git a/content/contracts-sui/1.x/api/access.mdx b/content/contracts-sui/1.x/api/access.mdx
index fe819308..da80b6aa 100644
--- a/content/contracts-sui/1.x/api/access.mdx
+++ b/content/contracts-sui/1.x/api/access.mdx
@@ -8,7 +8,7 @@ This page documents the public API of `openzeppelin_access` for OpenZeppelin Con
 
 <APIGithubLinkHeader
   moduleName="two_step_transfer"
-  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/contracts/access/sources/ownership_transfer/two_step.move"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/two_step.move"
 />
 
 ```move
@@ -307,7 +307,7 @@ Raised when caller is not the designated prospective owner in `accept_transfer`.
 
 <APIGithubLinkHeader
   moduleName="delayed_transfer"
-  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/contracts/access/sources/ownership_transfer/delayed.move"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/delayed.move"
 />
 
 ```move
diff --git a/content/contracts-sui/1.x/api/fixed-point.mdx b/content/contracts-sui/1.x/api/fixed-point.mdx
new file mode 100644
index 00000000..7f136f32
--- /dev/null
+++ b/content/contracts-sui/1.x/api/fixed-point.mdx
@@ -0,0 +1,1119 @@
+---
+title: Fixed-Point Math API Reference
+---
+
+This page documents the public API of `openzeppelin_fp_math` for OpenZeppelin Contracts for Sui `v1.x`.
+
+The package provides two decimal fixed-point types with 9 decimals (matching Sui coin precision):
+
+- `UD30x9`: unsigned, backed by `u128`.
+- `SD29x9`: signed (two's complement), backed by `u128`.
+
+Each type has a base module that holds the arithmetic, comparison, and bitwise functions, and a conversion module that scales whole integers in and out of fixed-point form.
+
+### `ud30x9` [toc] [#ud30x9]
+
+<APIGithubLinkHeader
+  moduleName="ud30x9"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/ud30x9/ud30x9.move"
+/>
+
+```move
+use openzeppelin_fp_math::ud30x9;
+```
+
+Defines the `UD30x9` unsigned decimal fixed-point type. Values represent unsigned real numbers as a `u128` scaled by `10^9`. The 9-decimal scale matches Sui coin precision and keeps offchain reasoning straightforward (`1.0` is `1_000_000_000`).
+
+This module owns the type, raw casting helpers (`wrap` / `unwrap`), and constant constructors. Arithmetic, comparison, and bitwise operations live in [`ud30x9_base`](#ud30x9_base). Whole-integer conversions live in [`ud30x9_convert`](#ud30x9_convert).
+
+Types
+
+- [`UD30x9`](#ud30x9-UD30x9)
+
+Functions
+
+- [`zero()`](#ud30x9-zero)
+- [`one()`](#ud30x9-one)
+- [`max()`](#ud30x9-max)
+- [`wrap(x)`](#ud30x9-wrap)
+- [`unwrap(x)`](#ud30x9-unwrap)
+
+#### Types [!toc] [#ud30x9-Types]
+
+<APIItem
+  functionSignature="struct UD30x9(u128) has copy, drop, store"
+  id="ud30x9-UD30x9"
+  kind="struct"
+>
+Unsigned decimal fixed-point type. The single `u128` field stores the raw bits of the value scaled by `10^9`.
+</APIItem>
+
+#### Functions [!toc] [#ud30x9-Functions]
+
+<APIItem
+  functionSignature="zero() -> UD30x9"
+  id="ud30x9-zero"
+  kind="public"
+>
+Returns the `UD30x9` representation of `0`.
+</APIItem>
+
+<APIItem
+  functionSignature="one() -> UD30x9"
+  id="ud30x9-one"
+  kind="public"
+>
+Returns the `UD30x9` representation of `1.0` (raw bits `10^9`).
+</APIItem>
+
+<APIItem
+  functionSignature="max() -> UD30x9"
+  id="ud30x9-max"
+  kind="public"
+>
+Returns the largest representable `UD30x9` value (raw bits `u128::MAX`).
+</APIItem>
+
+<APIItem
+  functionSignature="wrap(x: u128) -> UD30x9"
+  id="ud30x9-wrap"
+  kind="public"
+>
+Wraps raw `u128` bits into a `UD30x9` value without scaling. The input is interpreted as fixed-point bits already scaled by `10^9`.
+
+INFO: Use [`ud30x9_convert::from_u64`](#ud30x9_convert-from_u64) / [`from_u128`](#ud30x9_convert-from_u128) when the input is a whole integer that you mean as `x.0`.
+</APIItem>
+
+<APIItem
+  functionSignature="unwrap(x: UD30x9) -> u128"
+  id="ud30x9-unwrap"
+  kind="public"
+>
+Returns the raw `u128` bits of a `UD30x9` value.
+</APIItem>
+
+### `ud30x9_base` [toc] [#ud30x9_base]
+
+<APIGithubLinkHeader
+  moduleName="ud30x9_base"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/ud30x9/ud30x9_base.move"
+/>
+
+```move
+use openzeppelin_fp_math::ud30x9_base;
+```
+
+Arithmetic, comparison, and bitwise functions for `UD30x9`. All entries are exported as method-style calls on `UD30x9` via `public use fun` declarations in `ud30x9`, so `x.add(y)` and `ud30x9_base::add(x, y)` are equivalent.
+
+Functions
+
+- Arithmetic: [`add`](#ud30x9_base-add), [`sub`](#ud30x9_base-sub), [`mul`](#ud30x9_base-mul), [`mul_trunc`](#ud30x9_base-mul_trunc), [`mul_away`](#ud30x9_base-mul_away), [`div`](#ud30x9_base-div), [`div_trunc`](#ud30x9_base-div_trunc), [`div_away`](#ud30x9_base-div_away), [`mod`](#ud30x9_base-mod), [`pow`](#ud30x9_base-pow), [`abs`](#ud30x9_base-abs), [`ceil`](#ud30x9_base-ceil), [`floor`](#ud30x9_base-floor), [`unchecked_add`](#ud30x9_base-unchecked_add), [`unchecked_sub`](#ud30x9_base-unchecked_sub)
+- Comparison: [`eq`](#ud30x9_base-eq), [`neq`](#ud30x9_base-neq), [`gt`](#ud30x9_base-gt), [`gte`](#ud30x9_base-gte), [`lt`](#ud30x9_base-lt), [`lte`](#ud30x9_base-lte), [`is_zero`](#ud30x9_base-is_zero)
+- Bitwise: [`and`](#ud30x9_base-and), [`and2`](#ud30x9_base-and2), [`or`](#ud30x9_base-or), [`xor`](#ud30x9_base-xor), [`not`](#ud30x9_base-not), [`lshift`](#ud30x9_base-lshift), [`unchecked_lshift`](#ud30x9_base-unchecked_lshift), [`rshift`](#ud30x9_base-rshift), [`unchecked_rshift`](#ud30x9_base-unchecked_rshift)
+- Cross-type casts: [`into_SD29x9`](#ud30x9_base-into_SD29x9), [`try_into_SD29x9`](#ud30x9_base-try_into_SD29x9)
+
+Errors
+
+- [`EOverflow`](#ud30x9_base-EOverflow)
+- [`EUnderflow`](#ud30x9_base-EUnderflow)
+- [`EDivideByZero`](#ud30x9_base-EDivideByZero)
+- [`ECannotBeConvertedToSD29x9`](#ud30x9_base-ECannotBeConvertedToSD29x9)
+- [`EInvalidShiftSize`](#ud30x9_base-EInvalidShiftSize)
+
+#### Functions [!toc] [#ud30x9_base-Functions]
+
+<APIItem
+  functionSignature="add(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-add"
+  kind="public"
+>
+Returns the sum `x + y`.
+
+Aborts with `EOverflow` if the sum exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="sub(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-sub"
+  kind="public"
+>
+Returns the difference `x - y`.
+
+Aborts with `EUnderflow` if `y > x` (the result would be negative, which is unrepresentable in `UD30x9`).
+</APIItem>
+
+<APIItem
+  functionSignature="mul(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-mul"
+  kind="public"
+>
+Returns the product `x * y`, rounded toward zero. Equivalent to [`mul_trunc`](#ud30x9_base-mul_trunc).
+
+Aborts with `EOverflow` if the result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mul_trunc(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-mul_trunc"
+  kind="public"
+>
+Returns the product `x * y`, rounded toward zero (truncating the fractional part).
+
+Aborts with `EOverflow` if the result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mul_away(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-mul_away"
+  kind="public"
+>
+Returns the product `x * y`, rounded away from zero when inexact.
+
+Aborts with `EOverflow` if the rounded result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-div"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded toward zero. Equivalent to [`div_trunc`](#ud30x9_base-div_trunc).
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div_trunc(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-div_trunc"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded toward zero (truncating the fractional part).
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div_away(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-div_away"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded away from zero when inexact. For example `1.0 / 3.0` returns `0.333333334`.
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the rounded result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mod(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-mod"
+  kind="public"
+>
+Returns the remainder of `x` divided by `y`.
+
+Aborts with `EDivideByZero` if `y` is zero.
+</APIItem>
+
+<APIItem
+  functionSignature="pow(x: UD30x9, exp: u8) -> UD30x9"
+  id="ud30x9_base-pow"
+  kind="public"
+>
+Returns an approximation of `x^exp` computed using binary exponentiation with fixed-point multiplication. Each intermediate multiply or square applies fixed-point truncation.
+
+Aborts with `EOverflow` if any intermediate or the final result exceeds the representable `UD30x9` range.
+
+NOTE: Because truncation is applied at intermediate steps, `pow` is approximate for most fractional values. Rounding error compounds as `exp` grows; results are biased toward zero; for `0 < x < 1` intermediate values can reach zero before the final mathematically scaled result would. Fixed-point multiplication is not associative under truncation, so the grouping used by binary exponentiation can affect the value.
+</APIItem>
+
+<APIItem
+  functionSignature="abs(x: UD30x9) -> UD30x9"
+  id="ud30x9_base-abs"
+  kind="public"
+>
+Returns `x` unchanged. `UD30x9` is unsigned, so the absolute value is identity. Provided for symmetry with `SD29x9::abs`.
+</APIItem>
+
+<APIItem
+  functionSignature="ceil(x: UD30x9) -> UD30x9"
+  id="ud30x9_base-ceil"
+  kind="public"
+>
+Rounds toward positive infinity to the next integer multiple of `10^9`. Returns `x` if it is already a whole multiple.
+
+Aborts with `EOverflow` if the rounded result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="floor(x: UD30x9) -> UD30x9"
+  id="ud30x9_base-floor"
+  kind="public"
+>
+Rounds toward zero to the nearest integer multiple of `10^9`.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_add(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-unchecked_add"
+  kind="public"
+>
+Returns the wrapping sum `x + y` modulo `2^128`. Does not abort on overflow.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_sub(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-unchecked_sub"
+  kind="public"
+>
+Returns the wrapping difference `x - y` modulo `2^128`. Does not abort on underflow.
+</APIItem>
+
+<APIItem
+  functionSignature="eq(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-eq"
+  kind="public"
+>
+Returns `true` if `x == y`.
+</APIItem>
+
+<APIItem
+  functionSignature="neq(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-neq"
+  kind="public"
+>
+Returns `true` if `x != y`.
+</APIItem>
+
+<APIItem
+  functionSignature="gt(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-gt"
+  kind="public"
+>
+Returns `true` if `x > y`.
+</APIItem>
+
+<APIItem
+  functionSignature="gte(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-gte"
+  kind="public"
+>
+Returns `true` if `x >= y`.
+</APIItem>
+
+<APIItem
+  functionSignature="lt(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-lt"
+  kind="public"
+>
+Returns `true` if `x < y`.
+</APIItem>
+
+<APIItem
+  functionSignature="lte(x: UD30x9, y: UD30x9) -> bool"
+  id="ud30x9_base-lte"
+  kind="public"
+>
+Returns `true` if `x <= y`.
+</APIItem>
+
+<APIItem
+  functionSignature="is_zero(x: UD30x9) -> bool"
+  id="ud30x9_base-is_zero"
+  kind="public"
+>
+Returns `true` if `x` is exactly zero.
+</APIItem>
+
+<APIItem
+  functionSignature="and(x: UD30x9, bits: u128) -> UD30x9"
+  id="ud30x9_base-and"
+  kind="public"
+>
+Returns the bitwise AND of `x`'s raw bits and the `u128` mask `bits`.
+</APIItem>
+
+<APIItem
+  functionSignature="and2(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-and2"
+  kind="public"
+>
+Returns the bitwise AND of two `UD30x9` raw bit patterns.
+</APIItem>
+
+<APIItem
+  functionSignature="or(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-or"
+  kind="public"
+>
+Returns the bitwise OR of two `UD30x9` raw bit patterns.
+</APIItem>
+
+<APIItem
+  functionSignature="xor(x: UD30x9, y: UD30x9) -> UD30x9"
+  id="ud30x9_base-xor"
+  kind="public"
+>
+Returns the bitwise XOR of two `UD30x9` raw bit patterns.
+</APIItem>
+
+<APIItem
+  functionSignature="not(x: UD30x9) -> UD30x9"
+  id="ud30x9_base-not"
+  kind="public"
+>
+Returns the bitwise NOT of `x`'s raw bits.
+</APIItem>
+
+<APIItem
+  functionSignature="lshift(x: UD30x9, bits: u8) -> UD30x9"
+  id="ud30x9_base-lshift"
+  kind="public"
+>
+Logical left shift on the underlying 128-bit representation by `bits` positions.
+
+Aborts with `EInvalidShiftSize` if `bits >= 128`.
+Aborts with `EOverflow` if the shift would consume non-zero high bits.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_lshift(x: UD30x9, bits: u8) -> UD30x9"
+  id="ud30x9_base-unchecked_lshift"
+  kind="public"
+>
+Logical left shift that truncates high bits past the 128-bit boundary and returns zero when `bits >= 128`.
+
+NOTE: Use [`lshift`](#ud30x9_base-lshift) when you want shift-size and overflow checks to abort.
+</APIItem>
+
+<APIItem
+  functionSignature="rshift(x: UD30x9, bits: u8) -> UD30x9"
+  id="ud30x9_base-rshift"
+  kind="public"
+>
+Logical right shift on the underlying 128-bit representation by `bits` positions.
+
+Aborts with `EInvalidShiftSize` if `bits >= 128`.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_rshift(x: UD30x9, bits: u8) -> UD30x9"
+  id="ud30x9_base-unchecked_rshift"
+  kind="public"
+>
+Logical right shift that returns zero when `bits >= 128`. Vacated high bits are filled with zeros.
+</APIItem>
+
+<APIItem
+  functionSignature="into_SD29x9(x: UD30x9) -> SD29x9"
+  id="ud30x9_base-into_SD29x9"
+  kind="public"
+>
+Casts a `UD30x9` value to `SD29x9` while preserving the scaled numeric meaning.
+
+Aborts with `ECannotBeConvertedToSD29x9` if `x` exceeds the maximum positive `SD29x9` magnitude (`2^127 - 1`).
+</APIItem>
+
+<APIItem
+  functionSignature="try_into_SD29x9(x: UD30x9) -> Option<SD29x9>"
+  id="ud30x9_base-try_into_SD29x9"
+  kind="public"
+>
+Returns `some(SD29x9)` when the cast fits in the positive `SD29x9` range, otherwise `none`.
+</APIItem>
+
+#### Errors [!toc] [#ud30x9_base-Errors]
+
+<APIItem
+  functionSignature="EOverflow"
+  id="ud30x9_base-EOverflow"
+  kind="error"
+>
+Raised when an arithmetic or shift result exceeds the representable `UD30x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="EUnderflow"
+  id="ud30x9_base-EUnderflow"
+  kind="error"
+>
+Raised when subtraction would produce a negative result, which is unrepresentable in `UD30x9`.
+</APIItem>
+
+<APIItem
+  functionSignature="EDivideByZero"
+  id="ud30x9_base-EDivideByZero"
+  kind="error"
+>
+Raised when a division or modulo operation receives a zero divisor.
+</APIItem>
+
+<APIItem
+  functionSignature="ECannotBeConvertedToSD29x9"
+  id="ud30x9_base-ECannotBeConvertedToSD29x9"
+  kind="error"
+>
+Raised when [`into_SD29x9`](#ud30x9_base-into_SD29x9) is called on a value above the `SD29x9` positive range.
+</APIItem>
+
+<APIItem
+  functionSignature="EInvalidShiftSize"
+  id="ud30x9_base-EInvalidShiftSize"
+  kind="error"
+>
+Raised when [`lshift`](#ud30x9_base-lshift) or [`rshift`](#ud30x9_base-rshift) is called with `bits >= 128`.
+</APIItem>
+
+### `ud30x9_convert` [toc] [#ud30x9_convert]
+
+<APIGithubLinkHeader
+  moduleName="ud30x9_convert"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/ud30x9/conversions.move"
+/>
+
+```move
+use openzeppelin_fp_math::ud30x9_convert;
+```
+
+Scale-aware conversions between whole unsigned integers and `UD30x9`. These functions apply or remove the `10^9` scale factor, so use them when your input or output represents a whole-integer quantity (e.g. `42` as `42.0`).
+
+For raw, non-scaling casts, use [`ud30x9::wrap`](#ud30x9-wrap) and [`ud30x9::unwrap`](#ud30x9-unwrap) instead.
+
+Functions
+
+- [`from_u64(x)`](#ud30x9_convert-from_u64)
+- [`from_u128(x)`](#ud30x9_convert-from_u128)
+- [`try_from_u128(x)`](#ud30x9_convert-try_from_u128)
+- [`to_u128_trunc(x)`](#ud30x9_convert-to_u128_trunc)
+- [`to_u64_trunc(x)`](#ud30x9_convert-to_u64_trunc)
+- [`try_to_u64_trunc(x)`](#ud30x9_convert-try_to_u64_trunc)
+
+Errors
+
+- [`EOverflow`](#ud30x9_convert-EOverflow)
+- [`EIntegerOverflow`](#ud30x9_convert-EIntegerOverflow)
+
+#### Functions [!toc] [#ud30x9_convert-Functions]
+
+<APIItem
+  functionSignature="from_u64(x: u64) -> UD30x9"
+  id="ud30x9_convert-from_u64"
+  kind="public"
+>
+Converts a whole `u64` integer into `UD30x9` by multiplying it by `10^9`. Cannot overflow because `u64::MAX * 10^9` fits in `u128`.
+</APIItem>
+
+<APIItem
+  functionSignature="from_u128(x: u128) -> UD30x9"
+  id="ud30x9_convert-from_u128"
+  kind="public"
+>
+Converts a whole `u128` integer into `UD30x9` by multiplying it by `10^9`.
+
+Aborts with `EOverflow` if `x * 10^9` would overflow the `UD30x9` raw representation.
+</APIItem>
+
+<APIItem
+  functionSignature="try_from_u128(x: u128) -> Option<UD30x9>"
+  id="ud30x9_convert-try_from_u128"
+  kind="public"
+>
+Returns `some(UD30x9)` when `x * 10^9` fits in the raw representation, otherwise `none`.
+</APIItem>
+
+<APIItem
+  functionSignature="to_u128_trunc(x: UD30x9) -> u128"
+  id="ud30x9_convert-to_u128_trunc"
+  kind="public"
+>
+Returns the whole-number portion of `x`, computed as `floor(x)`.
+</APIItem>
+
+<APIItem
+  functionSignature="to_u64_trunc(x: UD30x9) -> u64"
+  id="ud30x9_convert-to_u64_trunc"
+  kind="public"
+>
+Returns the truncated whole-number portion of `x` as `u64`.
+
+Aborts with `EIntegerOverflow` if the truncated value exceeds `u64::MAX`.
+</APIItem>
+
+<APIItem
+  functionSignature="try_to_u64_trunc(x: UD30x9) -> Option<u64>"
+  id="ud30x9_convert-try_to_u64_trunc"
+  kind="public"
+>
+Returns `some(u64)` when the truncated whole-number portion fits in `u64`, otherwise `none`.
+</APIItem>
+
+#### Errors [!toc] [#ud30x9_convert-Errors]
+
+<APIItem
+  functionSignature="EOverflow"
+  id="ud30x9_convert-EOverflow"
+  kind="error"
+>
+Raised when a whole integer cannot be scaled into the `UD30x9` raw representation.
+</APIItem>
+
+<APIItem
+  functionSignature="EIntegerOverflow"
+  id="ud30x9_convert-EIntegerOverflow"
+  kind="error"
+>
+Raised when a truncated whole part does not fit in `u64`.
+</APIItem>
+
+### `sd29x9` [toc] [#sd29x9]
+
+<APIGithubLinkHeader
+  moduleName="sd29x9"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/sd29x9/sd29x9.move"
+/>
+
+```move
+use openzeppelin_fp_math::sd29x9;
+```
+
+Defines the `SD29x9` signed decimal fixed-point type. Values represent signed real numbers as a two's complement `u128` scaled by `10^9`. Useful for balance deltas and any quantity that can dip below zero.
+
+This module owns the type, raw casting helpers (`wrap` / `unwrap`), and constant constructors (`zero`, `one`, `min`, `max`). Arithmetic, comparison, and cross-type casts live in [`sd29x9_base`](#sd29x9_base). Whole-integer conversions live in [`sd29x9_convert`](#sd29x9_convert).
+
+Types
+
+- [`SD29x9`](#sd29x9-SD29x9)
+
+Functions
+
+- [`zero()`](#sd29x9-zero)
+- [`one()`](#sd29x9-one)
+- [`min()`](#sd29x9-min)
+- [`max()`](#sd29x9-max)
+- [`wrap(x, is_negative)`](#sd29x9-wrap)
+- [`unwrap(x)`](#sd29x9-unwrap)
+
+Errors
+
+- [`EOverflow`](#sd29x9-EOverflow)
+
+#### Types [!toc] [#sd29x9-Types]
+
+<APIItem
+  functionSignature="struct SD29x9(u128) has copy, drop, store"
+  id="sd29x9-SD29x9"
+  kind="struct"
+>
+Signed decimal fixed-point type. The single `u128` field stores a two's complement representation scaled by `10^9`.
+</APIItem>
+
+#### Functions [!toc] [#sd29x9-Functions]
+
+<APIItem
+  functionSignature="zero() -> SD29x9"
+  id="sd29x9-zero"
+  kind="public"
+>
+Returns the `SD29x9` representation of `0`.
+</APIItem>
+
+<APIItem
+  functionSignature="one() -> SD29x9"
+  id="sd29x9-one"
+  kind="public"
+>
+Returns the `SD29x9` representation of `1.0` (raw bits `10^9`).
+</APIItem>
+
+<APIItem
+  functionSignature="min() -> SD29x9"
+  id="sd29x9-min"
+  kind="public"
+>
+Returns the smallest representable `SD29x9` value, namely `-2^127`.
+
+NOTE: `+2^127` is not representable, so several arithmetic operations (such as `abs` and `negate`) abort when called on `min`.
+</APIItem>
+
+<APIItem
+  functionSignature="max() -> SD29x9"
+  id="sd29x9-max"
+  kind="public"
+>
+Returns the largest representable `SD29x9` value, namely `2^127 - 1`.
+</APIItem>
+
+<APIItem
+  functionSignature="wrap(x: u128, is_negative: bool) -> SD29x9"
+  id="sd29x9-wrap"
+  kind="public"
+>
+Wraps a `u128` magnitude plus a sign flag into a raw `SD29x9` value. The input must be a pure magnitude and must not already include a sign bit. When `is_negative` is `true`, the value is converted to its two's complement form.
+
+Aborts with `EOverflow` if `x` exceeds the maximum positive magnitude (`2^127 - 1`).
+
+NOTE: Cannot construct the minimum value. Use [`min`](#sd29x9-min) for that.
+</APIItem>
+
+<APIItem
+  functionSignature="unwrap(x: SD29x9) -> u128"
+  id="sd29x9-unwrap"
+  kind="public"
+>
+Returns the raw `u128` two's complement bits of an `SD29x9` value.
+</APIItem>
+
+#### Errors [!toc] [#sd29x9-Errors]
+
+<APIItem
+  functionSignature="EOverflow"
+  id="sd29x9-EOverflow"
+  kind="error"
+>
+Raised when [`wrap`](#sd29x9-wrap) is called with a magnitude that exceeds `2^127 - 1`.
+</APIItem>
+
+### `sd29x9_base` [toc] [#sd29x9_base]
+
+<APIGithubLinkHeader
+  moduleName="sd29x9_base"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/sd29x9/sd29x9_base.move"
+/>
+
+```move
+use openzeppelin_fp_math::sd29x9_base;
+```
+
+Arithmetic, comparison, and cross-type casts for `SD29x9`. All entries are exported as method-style calls on `SD29x9` via `public use fun` declarations in `sd29x9`, so `x.add(y)` and `sd29x9_base::add(x, y)` are equivalent.
+
+Types
+
+- [`Components`](#sd29x9_base-Components)
+
+Functions
+
+- Arithmetic: [`add`](#sd29x9_base-add), [`sub`](#sd29x9_base-sub), [`mul`](#sd29x9_base-mul), [`mul_trunc`](#sd29x9_base-mul_trunc), [`mul_away`](#sd29x9_base-mul_away), [`div`](#sd29x9_base-div), [`div_trunc`](#sd29x9_base-div_trunc), [`div_away`](#sd29x9_base-div_away), [`mod`](#sd29x9_base-mod), [`rem`](#sd29x9_base-rem), [`pow`](#sd29x9_base-pow), [`negate`](#sd29x9_base-negate), [`abs`](#sd29x9_base-abs), [`ceil`](#sd29x9_base-ceil), [`floor`](#sd29x9_base-floor), [`unchecked_add`](#sd29x9_base-unchecked_add), [`unchecked_sub`](#sd29x9_base-unchecked_sub)
+- Comparison: [`eq`](#sd29x9_base-eq), [`neq`](#sd29x9_base-neq), [`gt`](#sd29x9_base-gt), [`gte`](#sd29x9_base-gte), [`lt`](#sd29x9_base-lt), [`lte`](#sd29x9_base-lte), [`is_zero`](#sd29x9_base-is_zero)
+- Cross-type casts: [`into_UD30x9`](#sd29x9_base-into_UD30x9), [`try_into_UD30x9`](#sd29x9_base-try_into_UD30x9)
+
+Errors
+
+- [`EOverflow`](#sd29x9_base-EOverflow)
+- [`EDivideByZero`](#sd29x9_base-EDivideByZero)
+- [`ECannotBeConvertedToUD30x9`](#sd29x9_base-ECannotBeConvertedToUD30x9)
+
+#### Types [!toc] [#sd29x9_base-Types]
+
+<APIItem
+  functionSignature="struct Components { neg: bool, mag: u256 } has copy, drop"
+  id="sd29x9_base-Components"
+  kind="struct"
+>
+Signed decomposition of an `SD29x9` value into a sign flag and a non-negative magnitude as `u256`. Returned by internal helpers; surfaced publicly so downstream tooling can pattern-match on it.
+</APIItem>
+
+#### Functions [!toc] [#sd29x9_base-Functions]
+
+<APIItem
+  functionSignature="add(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-add"
+  kind="public"
+>
+Returns the sum `x + y`.
+
+Aborts with `EOverflow` if the resulting magnitude exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="sub(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-sub"
+  kind="public"
+>
+Returns the difference `x - y`.
+
+Aborts with `EOverflow` if the resulting magnitude exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mul(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-mul"
+  kind="public"
+>
+Returns the product `x * y`, rounded toward zero. Equivalent to [`mul_trunc`](#sd29x9_base-mul_trunc).
+
+Aborts with `EOverflow` if the result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mul_trunc(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-mul_trunc"
+  kind="public"
+>
+Returns the product `x * y`, rounded toward zero (truncating).
+
+Aborts with `EOverflow` if the result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="mul_away(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-mul_away"
+  kind="public"
+>
+Returns the product `x * y`, rounded away from zero when inexact. For example `1.000000001 * 1.000000001` returns `1.000000003`, and `-1.000000001 * 1.000000001` returns `-1.000000003`.
+
+Aborts with `EOverflow` if the rounded magnitude exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-div"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded toward zero. Equivalent to [`div_trunc`](#sd29x9_base-div_trunc).
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div_trunc(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-div_trunc"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded toward zero (truncating).
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="div_away(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-div_away"
+  kind="public"
+>
+Returns the quotient `x / y`, rounded away from zero when inexact. For example `1.0 / 3.0` returns `0.333333334`, and `-1.0 / 3.0` returns `-0.333333334`.
+
+Aborts with `EDivideByZero` if `y` is zero.
+Aborts with `EOverflow` if the rounded magnitude exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="rem(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-rem"
+  kind="public"
+>
+Returns the truncating remainder of `x` divided by `y`. The magnitude is `abs(x) % abs(y)` and the sign of the result follows the dividend `x`.
+
+Aborts with `EDivideByZero` if `y` is zero.
+
+NOTE: `rem` follows truncating remainder semantics. Use [`mod`](#sd29x9_base-mod) for Euclidean (always non-negative) remainder.
+</APIItem>
+
+<APIItem
+  functionSignature="mod(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-mod"
+  kind="public"
+>
+Returns the Euclidean remainder of `x` divided by `y`. The result is always non-negative and satisfies `0 <= result < abs(y)`.
+
+Aborts with `EDivideByZero` if `y` is zero.
+</APIItem>
+
+<APIItem
+  functionSignature="pow(x: SD29x9, exp: u8) -> SD29x9"
+  id="sd29x9_base-pow"
+  kind="public"
+>
+Returns an approximation of `x^exp` computed using binary exponentiation with fixed-point multiplication. Each intermediate multiply or square applies fixed-point truncation.
+
+Aborts with `EOverflow` if any intermediate or the final result exceeds the representable `SD29x9` range.
+
+NOTE: As with `UD30x9::pow`, results are biased toward zero, error compounds with `exp`, and binary-exponentiation grouping affects the value because fixed-point multiplication is not associative under truncation.
+</APIItem>
+
+<APIItem
+  functionSignature="negate(x: SD29x9) -> SD29x9"
+  id="sd29x9_base-negate"
+  kind="public"
+>
+Returns `-x`.
+
+Aborts with `EOverflow` if `x` is the minimum representable value (`-2^127`), because `+2^127` is not representable.
+</APIItem>
+
+<APIItem
+  functionSignature="abs(x: SD29x9) -> SD29x9"
+  id="sd29x9_base-abs"
+  kind="public"
+>
+Returns the absolute value of `x`.
+
+Aborts with `EOverflow` if `x` is the minimum representable value (`-2^127`).
+</APIItem>
+
+<APIItem
+  functionSignature="ceil(x: SD29x9) -> SD29x9"
+  id="sd29x9_base-ceil"
+  kind="public"
+>
+Rounds toward positive infinity to the nearest integer multiple of `10^9`.
+
+Aborts with `EOverflow` if the rounded result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="floor(x: SD29x9) -> SD29x9"
+  id="sd29x9_base-floor"
+  kind="public"
+>
+Rounds toward negative infinity to the nearest integer multiple of `10^9`.
+
+Aborts with `EOverflow` if the rounded negative result magnitude exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_add(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-unchecked_add"
+  kind="public"
+>
+Returns the wrapping sum of the raw bit patterns modulo `2^128`. Does not abort on overflow.
+</APIItem>
+
+<APIItem
+  functionSignature="unchecked_sub(x: SD29x9, y: SD29x9) -> SD29x9"
+  id="sd29x9_base-unchecked_sub"
+  kind="public"
+>
+Returns the wrapping difference of the raw bit patterns modulo `2^128`. Does not abort on underflow.
+</APIItem>
+
+<APIItem
+  functionSignature="eq(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-eq"
+  kind="public"
+>
+Returns `true` if `x` and `y` have identical underlying bits.
+</APIItem>
+
+<APIItem
+  functionSignature="neq(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-neq"
+  kind="public"
+>
+Returns `true` if `x != y`.
+</APIItem>
+
+<APIItem
+  functionSignature="gt(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-gt"
+  kind="public"
+>
+Returns `true` if `x > y` under signed comparison.
+</APIItem>
+
+<APIItem
+  functionSignature="gte(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-gte"
+  kind="public"
+>
+Returns `true` if `x >= y` under signed comparison.
+</APIItem>
+
+<APIItem
+  functionSignature="lt(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-lt"
+  kind="public"
+>
+Returns `true` if `x < y` under signed comparison.
+</APIItem>
+
+<APIItem
+  functionSignature="lte(x: SD29x9, y: SD29x9) -> bool"
+  id="sd29x9_base-lte"
+  kind="public"
+>
+Returns `true` if `x <= y` under signed comparison.
+</APIItem>
+
+<APIItem
+  functionSignature="is_zero(x: SD29x9) -> bool"
+  id="sd29x9_base-is_zero"
+  kind="public"
+>
+Returns `true` if `x` is exactly zero.
+</APIItem>
+
+<APIItem
+  functionSignature="into_UD30x9(x: SD29x9) -> UD30x9"
+  id="sd29x9_base-into_UD30x9"
+  kind="public"
+>
+Casts a non-negative `SD29x9` value to `UD30x9` while preserving the scaled numeric meaning.
+
+Aborts with `ECannotBeConvertedToUD30x9` if `x` is negative.
+</APIItem>
+
+<APIItem
+  functionSignature="try_into_UD30x9(x: SD29x9) -> Option<UD30x9>"
+  id="sd29x9_base-try_into_UD30x9"
+  kind="public"
+>
+Returns `some(UD30x9)` when `x` is non-negative, otherwise `none`.
+</APIItem>
+
+#### Errors [!toc] [#sd29x9_base-Errors]
+
+<APIItem
+  functionSignature="EOverflow"
+  id="sd29x9_base-EOverflow"
+  kind="error"
+>
+Raised when an arithmetic result exceeds the representable `SD29x9` range.
+</APIItem>
+
+<APIItem
+  functionSignature="EDivideByZero"
+  id="sd29x9_base-EDivideByZero"
+  kind="error"
+>
+Raised when a division, modulo, or remainder operation receives a zero divisor.
+</APIItem>
+
+<APIItem
+  functionSignature="ECannotBeConvertedToUD30x9"
+  id="sd29x9_base-ECannotBeConvertedToUD30x9"
+  kind="error"
+>
+Raised when [`into_UD30x9`](#sd29x9_base-into_UD30x9) is called on a negative value.
+</APIItem>
+
+### `sd29x9_convert` [toc] [#sd29x9_convert]
+
+<APIGithubLinkHeader
+  moduleName="sd29x9_convert"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/fixed_point/sources/sd29x9/conversions.move"
+/>
+
+```move
+use openzeppelin_fp_math::sd29x9_convert;
+```
+
+Scale-aware conversions between whole signed magnitudes and `SD29x9`. Inputs use an unsigned magnitude plus a sign flag because Move does not provide a native signed integer type for this package; outputs return either a single magnitude (when sign is asserted) or a `(magnitude, is_negative)` pair.
+
+For raw, non-scaling casts, use [`sd29x9::wrap`](#sd29x9-wrap) and [`sd29x9::unwrap`](#sd29x9-unwrap) instead.
+
+Functions
+
+- [`from_u64(x, is_negative)`](#sd29x9_convert-from_u64)
+- [`from_u128(x, is_negative)`](#sd29x9_convert-from_u128)
+- [`try_from_u128(x, is_negative)`](#sd29x9_convert-try_from_u128)
+- [`to_parts_trunc(x)`](#sd29x9_convert-to_parts_trunc)
+- [`to_u128_trunc(x)`](#sd29x9_convert-to_u128_trunc)
+- [`try_to_u128_trunc(x)`](#sd29x9_convert-try_to_u128_trunc)
+- [`to_u64_trunc(x)`](#sd29x9_convert-to_u64_trunc)
+- [`try_to_u64_trunc(x)`](#sd29x9_convert-try_to_u64_trunc)
+
+Errors
+
+- [`EOverflow`](#sd29x9_convert-EOverflow)
+- [`ENegativeValue`](#sd29x9_convert-ENegativeValue)
+- [`EIntegerOverflow`](#sd29x9_convert-EIntegerOverflow)
+
+#### Functions [!toc] [#sd29x9_convert-Functions]
+
+<APIItem
+  functionSignature="from_u64(x: u64, is_negative: bool) -> SD29x9"
+  id="sd29x9_convert-from_u64"
+  kind="public"
+>
+Converts a whole `u64` magnitude into `SD29x9` by multiplying it by `10^9` and applying the provided sign.
+</APIItem>
+
+<APIItem
+  functionSignature="from_u128(x: u128, is_negative: bool) -> SD29x9"
+  id="sd29x9_convert-from_u128"
+  kind="public"
+>
+Converts a whole `u128` magnitude into `SD29x9` by multiplying it by `10^9` and applying the provided sign.
+
+Aborts with `EOverflow` if `x * 10^9` would overflow the `SD29x9` raw representation.
+</APIItem>
+
+<APIItem
+  functionSignature="try_from_u128(x: u128, is_negative: bool) -> Option<SD29x9>"
+  id="sd29x9_convert-try_from_u128"
+  kind="public"
+>
+Returns `some(SD29x9)` when the scaled magnitude fits, otherwise `none`.
+</APIItem>
+
+<APIItem
+  functionSignature="to_parts_trunc(x: SD29x9) -> (u128, bool)"
+  id="sd29x9_convert-to_parts_trunc"
+  kind="public"
+>
+Returns `(magnitude, is_negative)` where `magnitude` is the truncated whole-number portion of `abs(x)`. `is_negative` is always `false` when the magnitude is zero.
+</APIItem>
+
+<APIItem
+  functionSignature="to_u128_trunc(x: SD29x9) -> u128"
+  id="sd29x9_convert-to_u128_trunc"
+  kind="public"
+>
+Returns the truncated whole-number portion of `x` as `u128`.
+
+Aborts with `ENegativeValue` if `x` is negative.
+</APIItem>
+
+<APIItem
+  functionSignature="try_to_u128_trunc(x: SD29x9) -> Option<u128>"
+  id="sd29x9_convert-try_to_u128_trunc"
+  kind="public"
+>
+Returns `some(u128)` when `x` is non-negative, otherwise `none`.
+</APIItem>
+
+<APIItem
+  functionSignature="to_u64_trunc(x: SD29x9) -> u64"
+  id="sd29x9_convert-to_u64_trunc"
+  kind="public"
+>
+Returns the truncated whole-number portion of `x` as `u64`.
+
+Aborts with `ENegativeValue` if `x` is negative.
+Aborts with `EIntegerOverflow` if the truncated magnitude exceeds `u64::MAX`.
+</APIItem>
+
+<APIItem
+  functionSignature="try_to_u64_trunc(x: SD29x9) -> Option<u64>"
+  id="sd29x9_convert-try_to_u64_trunc"
+  kind="public"
+>
+Returns `some(u64)` when `x` is non-negative and the truncated whole-number portion fits in `u64`, otherwise `none`.
+</APIItem>
+
+#### Errors [!toc] [#sd29x9_convert-Errors]
+
+<APIItem
+  functionSignature="EOverflow"
+  id="sd29x9_convert-EOverflow"
+  kind="error"
+>
+Raised when a whole signed magnitude cannot be scaled into the `SD29x9` raw representation.
+</APIItem>
+
+<APIItem
+  functionSignature="ENegativeValue"
+  id="sd29x9_convert-ENegativeValue"
+  kind="error"
+>
+Raised when a negative `SD29x9` value is converted to an unsigned integer type.
+</APIItem>
+
+<APIItem
+  functionSignature="EIntegerOverflow"
+  id="sd29x9_convert-EIntegerOverflow"
+  kind="error"
+>
+Raised when a truncated whole part does not fit in `u64`.
+</APIItem>
diff --git a/content/contracts-sui/1.x/api/math.mdx b/content/contracts-sui/1.x/api/math.mdx
index 3f9456e6..ebcd923c 100644
--- a/content/contracts-sui/1.x/api/math.mdx
+++ b/content/contracts-sui/1.x/api/math.mdx
@@ -8,7 +8,7 @@ This page documents the public API of `openzeppelin_math` for OpenZeppelin Contr
 
 <APIGithubLinkHeader
   moduleName="rounding"
-  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/rounding.move"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/rounding.move"
 />
 
 ```move
@@ -67,7 +67,7 @@ Returns `RoundingMode::Nearest` (round-half-up behavior).
 
 <APIGithubLinkHeader
   moduleName="decimal_scaling"
-  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/decimal_scaling.move"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/decimal_scaling.move"
 />
 
 ```move
@@ -134,12 +134,12 @@ Each module wraps shared arithmetic helpers with width-specific bit limits and r
 
 Source modules:
 
-- [`u8.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u8.move)
-- [`u16.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u16.move)
-- [`u32.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u32.move)
-- [`u64.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u64.move)
-- [`u128.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u128.move)
-- [`u256.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u256.move)
+- [`u8.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u8.move)
+- [`u16.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u16.move)
+- [`u32.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u32.move)
+- [`u64.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u64.move)
+- [`u128.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u128.move)
+- [`u256.move`](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u256.move)
 
 Functions
 
@@ -156,6 +156,7 @@ Functions
 - [`sqrt(value, rounding_mode)`](#width-sqrt)
 - [`inv_mod(value, modulus)`](#width-inv_mod)
 - [`mul_mod(a, b, modulus)`](#width-mul_mod)
+- [`is_power_of_ten(n)`](#width-is_power_of_ten)
 
 #### Functions [!toc] [#width-Functions]
 
@@ -271,11 +272,19 @@ Computes `(a * b) mod modulus`.
 Aborts when `modulus` is zero.
 </APIItem>
 
+<APIItem
+  functionSignature="is_power_of_ten(n: Int) -> bool"
+  id="width-is_power_of_ten"
+  kind="public"
+>
+Returns `true` when `n` is a power of ten within the width's range. The check is implemented as a width-specific lookup table, so it is O(1) and never aborts.
+</APIItem>
+
 ### `u512` [toc] [#u512]
 
 <APIGithubLinkHeader
   moduleName="u512"
-  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/math/core/sources/u512.move"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/u512.move"
 />
 
 ```move
@@ -420,3 +429,43 @@ Raised when `div_rem_u256` is called with `divisor = 0`.
 >
 Raised when internal division remainder invariants are violated.
 </APIItem>
+
+### `vector` [toc] [#vector]
+
+<APIGithubLinkHeader
+  moduleName="vector"
+  link="https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/math/core/sources/vector.move"
+/>
+
+```move
+use openzeppelin_math::vector;
+```
+
+Generic in-place sorting macros built on iterative quicksort with three-way partitioning (Dutch National Flag) and median-of-three pivot selection. The macros use an explicit stack so they work on arbitrarily large vectors without hitting Move macro recursion limits.
+
+Functions
+
+- [`quick_sort!(vec)`](#vector-quick_sort)
+- [`quick_sort_by!(vec, le)`](#vector-quick_sort_by)
+
+#### Functions [!toc] [#vector-Functions]
+
+<APIItem
+  functionSignature="macro fun quick_sort<$Int>($vec: &mut vector<$Int>)"
+  id="vector-quick_sort"
+  kind="public"
+>
+Sorts an unsigned integer vector in ascending order in place. Generic over any unsigned integer type (`u8`, `u16`, `u32`, `u64`, `u128`, `u256`).
+
+NOTE: Unstable sort. Average time complexity is `O(n log n)`; theoretical worst case is `O(n^2)`, mitigated by median-of-three pivot selection and three-way partitioning.
+</APIItem>
+
+<APIItem
+  functionSignature="macro fun quick_sort_by<$T>($vec: &mut vector<$T>, $le: |&$T, &$T| -> bool)"
+  id="vector-quick_sort_by"
+  kind="public"
+>
+Sorts a vector in place using a caller-supplied comparison function. The comparator must implement **non-strict** ordering (`<=` for ascending, `>=` for descending) — using a strict comparator (`<` or `>`) defeats three-way partitioning and degrades performance to `O(n^2)` when duplicates are present.
+
+NOTE: Unstable sort. The same complexity caveats as [`quick_sort`](#vector-quick_sort) apply.
+</APIItem>
diff --git a/content/contracts-sui/1.x/fixed-point.mdx b/content/contracts-sui/1.x/fixed-point.mdx
new file mode 100644
index 00000000..1449de91
--- /dev/null
+++ b/content/contracts-sui/1.x/fixed-point.mdx
@@ -0,0 +1,116 @@
+---
+title: Fixed-Point Math
+---
+
+The `openzeppelin_fp_math` package adds two decimal fixed-point types with 9 decimals of precision, matching Sui's native coin precision (`10^9`). It is the right tool whenever you need real-valued arithmetic — prices, fees, rates, ratios, balance deltas — without giving up determinism or onchain auditability.
+
+The package complements `openzeppelin_math`, which covers integer arithmetic. Use `openzeppelin_math` when your values are whole numbers; reach for `openzeppelin_fp_math` when fractional values are part of the protocol.
+
+## Why a 9-decimal scale
+
+- Matches Sui's native coin decimals, so converting between token amounts and fixed-point values is straightforward.
+- Decimal scale is intuitive for humans, UIs, and offchain systems — `1.5` is `1_500_000_000`, no binary fixed-point surprises.
+- Fits in `u128`, keeping storage and arithmetic light compared to `u256`-based decimal types.
+
+## The two types
+
+- [`UD30x9`](/contracts-sui/1.x/api/fixed-point#ud30x9) — unsigned. Decimal range from `0` to roughly `3.4 × 10^29`.
+- [`SD29x9`](/contracts-sui/1.x/api/fixed-point#sd29x9) — signed (two's complement). Decimal range from roughly `-1.7 × 10^29` to `1.7 × 10^29`. Useful for balance deltas, signed adjustments, and any quantity that can dip below zero.
+
+## Usage
+
+Add the dependency in `Move.toml`:
+
+```toml
+[dependencies]
+openzeppelin_fp_math = { r.mvr = "@openzeppelin-move/fixed-point-math" }
+```
+
+Import the modules you need:
+
+```move
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+```
+
+## Casting vs converting
+
+Two distinct ways to move into and out of fixed-point form:
+
+- **Casting** — `wrap` / `unwrap` and cross-type casts. Preserves the underlying scaled bits. Use when the value is already in raw fixed-point form.
+- **Converting** — the `*_convert` modules. Applies or removes the `10^9` scale factor. Use when the input is a whole integer like `42` and you mean `42.0`.
+
+## Examples
+
+### Build a fixed-point value from a whole integer
+
+```move
+module my_sui_app::pricing;
+
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+
+public fun reference_price(): ud30x9::UD30x9 {
+    // 1.5 = 1.0 + 0.500000000
+    ud30x9_convert::from_u128(1).add(ud30x9::wrap(500_000_000))
+}
+```
+
+### Multiply with explicit rounding
+
+```move
+module my_sui_app::quote;
+
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+
+public fun apply_fee(amount: ud30x9::UD30x9, fee_rate: ud30x9::UD30x9): ud30x9::UD30x9 {
+    // Round away from zero so quoted fees never under-charge.
+    amount.mul_away(fee_rate)
+}
+```
+
+### Track a signed balance delta
+
+```move
+module my_sui_app::ledger;
+
+use openzeppelin_fp_math::{sd29x9, sd29x9_convert};
+
+public fun apply_adjustment(
+    balance: sd29x9::SD29x9,
+    magnitude: u128,
+    is_negative: bool,
+): sd29x9::SD29x9 {
+    let delta = sd29x9_convert::from_u128(magnitude, is_negative);
+    balance.add(delta)
+}
+```
+
+### Convert back to a whole integer
+
+```move
+module my_sui_app::settlement;
+
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+
+/// Truncate a `UD30x9` value to a `u64` token amount.
+public fun settle(amount: ud30x9::UD30x9): u64 {
+    amount.to_u64_trunc()
+}
+```
+
+## Choosing a function
+
+- `mul`, `div` — round toward zero. Equivalent to `mul_trunc`, `div_trunc`. Use as the default when rounding direction does not matter.
+- `mul_trunc`, `div_trunc` — round toward zero (truncate). Use when you want to spell the rounding direction out at the call site.
+- `mul_away`, `div_away` — round away from zero when inexact. Use for fees, slippage caps, and protocol-side accounting where rounding should never favor the user against the protocol.
+- `unchecked_add`, `unchecked_sub` — wrap modulo `2^128` instead of aborting on overflow/underflow. Use only when you have already proved the operation is safe and you want to avoid the abort path; otherwise prefer `add` / `sub`.
+- `pow` — approximate, biased toward zero, and not associative under truncation. Reasonable for small, integer exponents over typical fixed-point ranges; verify expected behavior at your application's exponent and operand magnitudes before relying on it.
+
+For `SD29x9` specifically, prefer `mod` (Euclidean, always non-negative) over `rem` (truncating, sign follows dividend) unless your protocol explicitly wants the truncating variant.
+
+<Callout type="warn">
+`SD29x9::min()` is `-2^127`. There is no representable `+2^127`, so calling `abs` or `negate` on `min()` aborts with `EOverflow`. Same caveat for `wrap(_, true)` at maximum magnitude.
+</Callout>
+
+## API Reference
+
+Use the full function-level reference here: [Fixed-Point Math API](/contracts-sui/1.x/api/fixed-point).
diff --git a/content/contracts-sui/1.x/learn/access-walkthrough.mdx b/content/contracts-sui/1.x/learn/access-walkthrough.mdx
index f4fc9a66..cb3bb287 100644
--- a/content/contracts-sui/1.x/learn/access-walkthrough.mdx
+++ b/content/contracts-sui/1.x/learn/access-walkthrough.mdx
@@ -70,7 +70,7 @@ If you try to drop the borrow token, return a different capability, or return it
 
 ## `two_step_transfer`
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/contracts/access/sources/ownership_transfer/two_step.move)
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/two_step.move)
 
 A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay, thus the transfer executes immediately once the recipient accepts.
 
@@ -155,7 +155,7 @@ Avoid using `two_step_transfer` in shared-object executor flows unless your desi
 
 ## `delayed_transfer`
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.0.0/contracts/access/sources/ownership_transfer/delayed.move)
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/delayed.move)
 
 A transfer policy that enforces a configurable minimum delay between scheduling and executing a transfer. The delay is set at wrap time and cannot be changed afterward. This creates a publicly visible window before any authority change takes effect, giving monitoring systems, DAOs, and individual users time to detect and respond.
 
diff --git a/content/contracts-sui/1.x/math.mdx b/content/contracts-sui/1.x/math.mdx
index 352b11b3..e06aa072 100644
--- a/content/contracts-sui/1.x/math.mdx
+++ b/content/contracts-sui/1.x/math.mdx
@@ -71,9 +71,14 @@ public fun scale_down_9_to_6(amount: u256): u64 {
 ## Picking the right primitives
 
 - `rounding`: shared rounding policy (`Down`, `Up`, `Nearest`) for value-sensitive paths.
-- `u8`, `u16`, `u32`, `u64`, `u128`, `u256`: same API surface across widths for portability.
+- `u8`, `u16`, `u32`, `u64`, `u128`, `u256`: same API surface across widths for portability. Each module also exposes `is_power_of_ten` for checking decimal scale.
 - `decimal_scaling`: decimal conversion between systems using different precision.
 - `u512`: wide intermediate support for high-precision arithmetic paths.
+- `vector`: in-place sorting macros (`quick_sort!`, `quick_sort_by!`) for unsigned integer vectors and arbitrary types with a custom comparator.
+
+## Need fractional values?
+
+For prices, fees, ratios, and signed deltas, use the companion [Fixed-Point Math](/contracts-sui/1.x/fixed-point) package. It provides 9-decimal `UD30x9` and `SD29x9` types backed by `u128`, with the same explicit-rounding philosophy as the integer modules above.
 
 ## API Reference
 
diff --git a/skills/docs-sync/SKILL.md b/skills/docs-sync/SKILL.md
index 0110e452..2298c15d 100644
--- a/skills/docs-sync/SKILL.md
+++ b/skills/docs-sync/SKILL.md
@@ -24,23 +24,20 @@ Do **not** trigger this skill for:
 
 ## Required runtime inputs
 
-Collect these before editing:
-
-- `<MODE>`: `interactive` or `automatic`.
-- `<CONTRACTS_REPO_PATH>`: local path to the contracts repo (runtime).
-- `<DOCS_REPO_PATH>`: local path to this docs repo (runtime).
-- `<BASE_COMMIT>`: contracts commit immediately **before** the change set.
-- `<HEAD_COMMIT>`: contracts commit at the **tip** of the change set.
-- `<LIBRARY_ID>`: docs slice id (e.g. `contracts-sui`).
-- `<DOCS_VERSION>`: docs version (e.g. `1.x`).
-- `<RELEASE_VERSION>`: human-facing release tag (e.g. `v1.1.0`).
-- `<DOCS_UPDATE_SCOPE>`: `full`, `api-only`, `guides-only`, or
-  `targeted:<paths>`. Default: `full`.
-
-Optional:
-
-- `<TARGET_AUDIENCE>`
-- `<DOCS_TONE>`
+The skill needs the inputs listed below. Callers may pre-supply any of
+them in the invocation prompt; whatever is missing is collected
+interactively in **Step 0** of `process.md` via `AskUserQuestion`. In
+`automatic` mode, missing required inputs are a hard failure — the
+skill will not invent SHAs, paths, or versions.
+
+Required: `<MODE>`, `<CONTRACTS_REPO_PATH>`, `<DOCS_REPO_PATH>`,
+`<BASE_COMMIT>`, `<HEAD_COMMIT>`, `<LIBRARY_ID>`, `<DOCS_VERSION>`,
+`<RELEASE_VERSION>`, `<DOCS_UPDATE_SCOPE>` (default `full`).
+
+Optional: `<TARGET_AUDIENCE>`, `<DOCS_TONE>`.
+
+See `process.md` Step 0 for defaults, prompt templates, and inline
+validation rules.
 
 ## Source-of-truth constraint
 
diff --git a/skills/docs-sync/process.md b/skills/docs-sync/process.md
index ca9e37c7..f77fdc80 100644
--- a/skills/docs-sync/process.md
+++ b/skills/docs-sync/process.md
@@ -9,6 +9,92 @@ explicitly prefixed with `<CONTRACTS_REPO_PATH>`.
 
 ---
 
+## Step 0 — Collect runtime inputs
+
+Inputs may arrive in two ways:
+
+1. **Pre-supplied** in the invocation prompt (`LIBRARY_ID=contracts-sui`,
+   `BASE_COMMIT=abc123`, etc.).
+2. **Collected interactively** here, using the `AskUserQuestion` tool,
+   for any required input the caller did not supply.
+
+Required inputs (see SKILL.md for full list): `<MODE>`,
+`<CONTRACTS_REPO_PATH>`, `<DOCS_REPO_PATH>`, `<BASE_COMMIT>`,
+`<HEAD_COMMIT>`, `<LIBRARY_ID>`, `<DOCS_VERSION>`, `<RELEASE_VERSION>`,
+`<DOCS_UPDATE_SCOPE>`.
+
+### 0.1 Resolve from caller args and defaults first
+
+Before prompting, fill in what can be inferred without the user:
+
+- `<DOCS_REPO_PATH>`: default to the current working directory if it is
+  the docs repo (verify by checking for `skills/docs-sync/SKILL.md`).
+- `<LIBRARY_ID>`: if exactly one file exists under
+  `skills/docs-sync/config/libraries/*.yml`, use that slice id.
+- `<DOCS_VERSION>`: if the resolved slice has exactly one version
+  directory under `docs.version_root`'s parent, use that.
+- `<DOCS_UPDATE_SCOPE>`: default to `full` unless the caller scoped it.
+- `<MODE>`: if not supplied, read `automation.default_mode` from the
+  resolved config; otherwise default to `interactive`.
+
+Record every default that was applied so the final report can list them
+as assumptions.
+
+### 0.2 If `<MODE>` resolves to `automatic`, do not prompt
+
+In `automatic` mode, missing required inputs are a hard failure. Stop
+with a clear message naming the missing fields. Do not invent SHAs,
+versions, or paths.
+
+### 0.3 Otherwise, prompt for missing inputs
+
+For each input still missing, ask the user via `AskUserQuestion`. Group
+related inputs into a single call (the tool accepts up to 4 questions
+per call). Use the templates below.
+
+**Bounded inputs — multiple choice** (let the user pick "Other" only
+when the listed options truly do not fit):
+
+- `<MODE>`: options `interactive` (Recommended) and `automatic`.
+- `<DOCS_UPDATE_SCOPE>`: options `full` (Recommended), `api-only`,
+  `guides-only`, `targeted:<paths>`.
+- `<LIBRARY_ID>`: options enumerated from the filenames under
+  `skills/docs-sync/config/libraries/*.yml`. If only one slice exists,
+  skip the prompt and apply it as the default.
+
+**Free-form inputs — ask via `AskUserQuestion` with a "Recommended"
+default option plus "Other" for custom input:**
+
+- `<CONTRACTS_REPO_PATH>`: an absolute filesystem path. No safe default
+  unless the user has previously supplied one this session.
+- `<BASE_COMMIT>` / `<HEAD_COMMIT>`: commit SHAs or refs in the
+  contracts repo. If reasonable, suggest the latest tag as `<BASE>` and
+  `HEAD` as `<HEAD>`; let the user override.
+- `<DOCS_VERSION>`: e.g. `1.x`. Suggest the highest existing version
+  directory in the slice.
+- `<RELEASE_VERSION>`: e.g. `v1.2.0`. No safe default; ask.
+
+### 0.4 Validate as you collect
+
+After collection, validate inline and re-prompt on failure rather than
+deferring to later steps:
+
+- Paths exist and are git repos (`git -C <path> rev-parse
+  --is-inside-work-tree`).
+- `<CONTRACTS_REPO_PATH>` is not the same as `<DOCS_REPO_PATH>`.
+- `<BASE_COMMIT>` and `<HEAD_COMMIT>` resolve in the contracts repo
+  (`git -C <CONTRACTS_REPO_PATH> rev-parse --verify <SHA>^{commit}`).
+- `<LIBRARY_ID>` has a config file at
+  `skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`.
+
+If a validation fails in interactive mode, re-prompt for just that
+field. If it fails in automatic mode (e.g. caller supplied a bad SHA),
+stop with a clear error.
+
+Once all inputs are present and validated, proceed to Step 1. Steps 3
+and 4 below still run, but become no-ops because the same checks have
+already passed.
+
 ## Step 1 — Select mode
 
 1. If the caller passed `<MODE>`, use it.
diff --git a/src/navigation/sui/current.json b/src/navigation/sui/current.json
index f2781876..fb1885d9 100644
--- a/src/navigation/sui/current.json
+++ b/src/navigation/sui/current.json
@@ -45,6 +45,11 @@
 				"name": "Integer Math",
 				"url": "/contracts-sui/1.x/math"
 			},
+			{
+				"type": "page",
+				"name": "Fixed-Point Math",
+				"url": "/contracts-sui/1.x/fixed-point"
+			},
 			{
 				"type": "page",
 				"name": "Access",
@@ -61,6 +66,11 @@
 				"name": "Integer Math",
 				"url": "/contracts-sui/1.x/api/math"
 			},
+			{
+				"type": "page",
+				"name": "Fixed-Point Math",
+				"url": "/contracts-sui/1.x/api/fixed-point"
+			},
 			{
 				"type": "page",
 				"name": "Access",

From 729a6803b2a9364f217659f4002748e287b32a6c Mon Sep 17 00:00:00 2001
From: Eric Nordelo <eric.nordelo39@gmail.com>
Date: Wed, 29 Apr 2026 16:11:23 +0200
Subject: [PATCH 3/5] feat: update skill

---
 content/contracts-sui/1.x/access.mdx          | 316 +++++++++++++-
 content/contracts-sui/1.x/fixed-point.mdx     | 390 ++++++++++++++++-
 content/contracts-sui/1.x/index.mdx           |  25 +-
 .../1.x/learn/access-walkthrough.mdx          | 331 ---------------
 content/contracts-sui/1.x/learn/index.mdx     |   8 -
 .../1.x/learn/math-walkthrough.mdx            | 342 ---------------
 content/contracts-sui/1.x/math.mdx            | 317 +++++++++++++-
 content/contracts-sui/index.mdx               |  15 +-
 skills/docs-sync/SKILL.md                     | 175 ++++++--
 skills/docs-sync/process.md                   | 392 ++++++++++++------
 .../docs-sync/references/proposals/README.md  |  48 +++
 .../proposals/g1-inputs-and-config.md         |  39 ++
 .../references/proposals/g2-api-delta.md      |  81 ++++
 .../references/proposals/g3-docs-edit-plan.md |  52 +++
 .../references/proposals/g4-page-rewrite.md   |  41 ++
 src/navigation/sui/current.json               |  22 -
 16 files changed, 1696 insertions(+), 898 deletions(-)
 delete mode 100644 content/contracts-sui/1.x/learn/access-walkthrough.mdx
 delete mode 100644 content/contracts-sui/1.x/learn/index.mdx
 delete mode 100644 content/contracts-sui/1.x/learn/math-walkthrough.mdx
 create mode 100644 skills/docs-sync/references/proposals/README.md
 create mode 100644 skills/docs-sync/references/proposals/g1-inputs-and-config.md
 create mode 100644 skills/docs-sync/references/proposals/g2-api-delta.md
 create mode 100644 skills/docs-sync/references/proposals/g3-docs-edit-plan.md
 create mode 100644 skills/docs-sync/references/proposals/g4-page-rewrite.md

diff --git a/content/contracts-sui/1.x/access.mdx b/content/contracts-sui/1.x/access.mdx
index d2672cee..ffaa78ae 100644
--- a/content/contracts-sui/1.x/access.mdx
+++ b/content/contracts-sui/1.x/access.mdx
@@ -2,6 +2,10 @@
 title: Access
 ---
 
+<Callout type="warn">
+The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+</Callout>
+
 The `openzeppelin_access` package provides ownership-transfer wrappers for privileged Sui objects (`T: key + store`), such as admin and treasury capabilities.
 
 Use this package when direct object transfer is too permissive for your protocol. It gives you explicit transfer workflows that are easier to review, monitor, and constrain with policy.
@@ -10,6 +14,8 @@ Use this package when direct object transfer is too permissive for your protocol
 This package is designed for single-owned objects. In `two_step_transfer`, `ctx.sender()` is stored as the owner-of-record for pending requests. Avoid using this policy directly in shared-object executor flows unless your design explicitly maps signer identity to cancel authority.
 </Callout>
 
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access)
+
 ## Usage
 
 Add the dependency in `Move.toml`:
@@ -25,7 +31,7 @@ Import the transfer policy module you want to use:
 use openzeppelin_access::two_step_transfer;
 ```
 
-## Examples
+## Quickstart example
 
 ```move
 module my_sui_app::admin;
@@ -47,9 +53,311 @@ public fun wrap_admin_cap(
 
 ## Choosing a transfer policy
 
-- Use `two_step_transfer` when the signer triggering transfer initiation is the same principal that should retain cancel authority.
-- Use `delayed_transfer` when protocol safety requires on-chain lead time before transfer or unwrap execution, and when initial wrapper custody should be assigned explicitly at wrap time.
+**Use `two_step_transfer` when:**
+
+- The transfer can execute immediately once confirmed.
+- The principal initiating the transfer is a known, controlled key.
+- The risk you are guarding against is human error (wrong or non-existent address), not timing.
+
+**Use `delayed_transfer` when:**
+
+- Your protocol requires on-chain lead time before authority changes.
+- Users, DAOs, or monitoring systems need a window to detect and respond.
+- The delay should be a reliable, inspectable commitment visible to anyone.
+
+**Combining both:** the modules accept any `T: key + store`, so they compose. You could wrap a capability in `delayed_transfer` for the timing guarantee and use a `two_step_transfer` flow at the scheduling step for address-confirmation safety.
+
+---
+
+## Why controlled transfers matter
+
+On Sui, `sui::transfer::transfer` is instant and irreversible. There is no confirmation step, no waiting period, and no cancel mechanism. For everyday objects this is fine. For privileged capability objects, such as admin caps, treasury caps, or upgrade authorities, a single mistaken or malicious transfer permanently moves control with no recourse.
+
+The `openzeppelin_access` package adds two transfer policies that sit between you and that irreversible `transfer` call:
+
+| Module | What it enforces | Analogy from Solidity |
+| --- | --- | --- |
+| `two_step_transfer` | Recipient must explicitly accept before the transfer completes | `Ownable2Step` |
+| `delayed_transfer` | Mandatory time delay before execution; anyone can observe the pending action | `TimelockController` on ownership |
+
+If you already know which policy you need, jump directly to [two\_step\_transfer](#two_step_transfer) or [delayed\_transfer](#delayed_transfer).
+
+## Wrapping and transfer policies
+
+Both modules use the same underlying mechanism: wrapping a capability inside a new object that enforces a transfer policy on it.
+
+When you call `wrap`, the capability is stored as a dynamic object field inside the wrapper. This means:
+
+- **The wrapper becomes the custody object.** You hold the wrapper, not the capability directly. To transfer or recover the capability, you go through the wrapper's policy.
+- **The underlying capability retains its on-chain ID.** Off-chain indexers and explorers can still discover and track it via the dynamic object field. Wrapping does not make the capability invisible.
+- **The wrapper intentionally omits the `store` ability.** Without `store`, the wrapper cannot be moved via `transfer::public_transfer`. Only the module's own functions (which use the privileged `transfer::transfer` internally) can move it. This is a deliberate design choice that prevents accidental transfers outside the policy.
+
+A `WrapExecuted` event is emitted when a capability is wrapped, creating an on-chain record of when the policy was applied.
+
+### Borrowing without unwrapping
+
+Both modules provide three ways to use the wrapped capability without changing ownership:
+
+**Immutable borrow** for read-only access:
+
+```move
+let cap_ref = wrapper.borrow(); // &AdminCap
+```
+
+**Mutable borrow** for updating the capability's internal state:
+
+```move
+let cap_mut = wrapper.borrow_mut(); // &mut AdminCap
+```
+
+**Temporary move** for functions that require the capability by value. This uses the hot potato pattern: `borrow_val` returns a `Borrow` struct with no abilities (`copy`, `drop`, `store`, `key` are all absent). The Move compiler enforces that it must be consumed by `return_val` before the transaction ends.
+
+```move
+let (cap, borrow_token) = wrapper.borrow_val();
+
+/// Use cap in functions that require it by value.
+wrapper.return_val(cap, borrow_token); // compiler enforces this call
+```
+
+If you try to drop the borrow token, return a different capability, or return it to the wrong wrapper, the transaction either won't compile or will abort at runtime.
+
+## `two_step_transfer`
+
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/two_step.move)
+
+A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay, thus the transfer executes immediately once the recipient accepts.
+
+This is the right choice when the principal initiating the transfer is a known, controlled key (a multisig, a hot wallet operated by the same team) and the risk you are guarding against is sending the capability to a wrong or non-existent address, which would permanently lock the capability with no way to recover it.
+
+### Step 1: Wrap the capability
+
+```move
+module my_sui_app::admin;
+
+use openzeppelin_access::two_step_transfer;
+
+public struct AdminCap has key, store { id: UID }
+
+/// Wrap and immediately initiate a transfer to `new_admin`.
+/// The wrapper is consumed by `initiate_transfer` and held
+/// inside the shared `PendingOwnershipTransfer` until the
+/// recipient accepts or the initiator cancels.
+public fun wrap_and_transfer(cap: AdminCap, new_admin: address, ctx: &mut TxContext) {
+    let wrapper = two_step_transfer::wrap(cap, ctx);
+    // Emits WrapExecuted
+
+    wrapper.initiate_transfer(new_admin, ctx);
+    // Emits TransferInitiated
+}
+```
+
+`wrap` stores the `AdminCap` inside a `TwoStepTransferWrapper<AdminCap>` and emits a `WrapExecuted` event. Because the wrapper lacks the `store` ability, it cannot be sent via `transfer::public_transfer`. The intended next step is to call `initiate_transfer`, which consumes the wrapper and creates a shared `PendingOwnershipTransfer<AdminCap>` object that both parties can interact with.
+
+### Step 2: Initiate a transfer
+
+`initiate_transfer` consumes the wrapper by value and creates a shared `PendingOwnershipTransfer<AdminCap>` object. The sender's address is recorded as `from` (the cancel authority), and the recipient's address is recorded as `to`.
+
+```move
+/// Called by the current wrapper owner. Consumes the wrapper.
+wrapper.initiate_transfer(new_admin_address, ctx);
+/// Emits TransferInitiated { wrapper_id, from, to }
+```
+
+After this call, the wrapper is held inside the pending request via transfer-to-object. The original owner no longer has it in their scope, but they retain the ability to cancel because their address is recorded as `from`.
+
+The `TransferInitiated` event contains the pending request's ID and the wrapper ID, allowing off-chain indexers to discover the shared `PendingOwnershipTransfer` object for the next step.
+
+### Step 3: Recipient accepts (or initiator cancels)
+
+The designated recipient calls `accept_transfer` to complete the handoff. This step uses Sui's [transfer-to-object (TTO)](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) pattern: the wrapper was transferred to the `PendingOwnershipTransfer` object in Step 2, so the recipient must provide a `Receiving<TwoStepTransferWrapper<AdminCap>>` ticket to claim it. The `Receiving` type is Sui's mechanism for retrieving objects that were sent to another object rather than to a wallet.
+
+```move
+/// Called by the address recorded as `to` (new_admin_address).
+/// `request` is the shared PendingOwnershipTransfer<AdminCap> object.
+/// `wrapper_ticket` is the Receiving<TwoStepTransferWrapper<AdminCap>> for the wrapper
+/// that was transferred to the request object.
+two_step_transfer::accept_transfer(request, wrapper_ticket, ctx);
+// Emits TransferAccepted { wrapper_id, from, to }
+```
+
+If the initiator changes their mind before the recipient accepts, they can cancel. The cancel call also requires the `Receiving` ticket for the wrapper:
+
+```move
+/// Called by the address recorded as `from` (the original initiator).
+two_step_transfer::cancel_transfer(request, wrapper_ticket, ctx);
+/// Wrapper is returned to the `from` address.
+```
+
+### Unwrapping
+
+To permanently reclaim the raw capability and destroy the wrapper:
+
+```move
+let admin_cap = wrapper.unwrap(ctx);
+```
+
+This bypasses the transfer flow entirely. Only the current wrapper owner can call it.
+
+### Security note on shared-object flows
+
+`initiate_transfer` records `ctx.sender()` as the cancel authority. In normal single-owner usage, this is the wallet holding the wrapper. However, if `initiate_transfer` is called inside a shared-object executor where any user can be the transaction sender, a malicious user could call `initiate_transfer` targeting their own address as recipient. They would become both the pending recipient and the sole cancel authority, locking out the legitimate owner.
+
+Avoid using `two_step_transfer` in shared-object executor flows unless your design explicitly maps signer identity to cancel authority.
+
+## `delayed_transfer`
+
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/delayed.move)
+
+A transfer policy that enforces a configurable minimum delay between scheduling and executing a transfer. The delay is set at wrap time and cannot be changed afterward. This creates a publicly visible window before any authority change takes effect, giving monitoring systems, DAOs, and individual users time to detect and respond.
+
+This is the right choice when your protocol requires on-chain lead time before a capability changes hands, for example, to allow an incident response process to detect a compromised key, or to give depositors time to exit before governance parameters change.
+
+### Step 1: Wrap with a delay
+
+```move
+module my_sui_app::treasury;
+
+use openzeppelin_access::delayed_transfer;
+
+public struct TreasuryCap has key, store { id: UID }
+
+const MIN_DELAY_MS: u64 = 86_400_000; // 24 hours
+
+/// Creates the wrapper and transfers it to ctx.sender() internally
+public fun wrap_treasury_cap(cap: TreasuryCap, ctx: &mut TxContext) {
+    delayed_transfer::wrap(cap, MIN_DELAY_MS, ctx.sender(), ctx);
+}
+```
+
+`wrap` creates a `DelayedTransferWrapper<TreasuryCap>`, stores the capability inside it as a dynamic object field, and transfers the wrapper to the specified `recipient` (here, the caller). A `WrapExecuted` event is emitted. Unlike `two_step_transfer::wrap` which returns the wrapper, `delayed_transfer::wrap` handles the transfer internally and has no return value.
+
+### Step 2: Schedule a transfer
+
+```move
+/// Called by the current wrapper owner.
+wrapper.schedule_transfer(new_owner_address, &clock, ctx);
+/// Emits TransferScheduled with execute_after_ms = clock.timestamp_ms() + min_delay_ms
+```
+
+The `Clock` object is Sui's shared on-chain clock. The deadline is computed as `clock.timestamp_ms() + min_delay_ms` and stored in the wrapper. Only one action can be pending at a time; scheduling a second without canceling the first aborts with `ETransferAlreadyScheduled`.
+
+During the delay window, the `TransferScheduled` event is visible on-chain. Monitoring systems, governance dashboards, or individual users watching the chain can detect the pending transfer and take action (e.g., withdrawing funds from the protocol) before it executes.
+
+<Callout type="warn">
+The `recipient` in `schedule_transfer` must be a wallet address, not an object ID. If the wrapper is transferred to an object via transfer-to-object (TTO), both the wrapper and the capability inside it become permanently locked. The `delayed_transfer` module does not implement a `Receiving`-based retrieval mechanism, so there is no way to borrow, unwrap, or further transfer a wrapper that has been sent to an object. Always verify that the scheduled recipient is an address controlled by a keypair.
+</Callout>
+
+### Step 3: Wait, then execute
+
+```move
+/// Callable after the delay window has passed.
+wrapper.execute_transfer(&clock, ctx);
+/// Emits OwnershipTransferred. Consumes the wrapper and delivers it to the recipient.
+```
+
+`execute_transfer` consumes the wrapper by value. After this call, the wrapper has been transferred to the scheduled recipient and no longer exists in the caller's scope. Calling it before `execute_after_ms` aborts with `EDelayNotElapsed`.
+
+### Scheduling an unwrap
+
+The same delay enforcement applies to recovering the raw capability:
+
+```move
+/// Schedule the unwrap
+wrapper.schedule_unwrap(&clock, ctx);
+/// Emits UnwrapScheduled
+
+/// After the delay has elapsed, executes the unwrap: Emits UnwrapExecuted, wrapper is consumed, and capability is returned.
+let treasury_cap = wrapper.unwrap(&clock, ctx);
+```
+
+### Canceling
+
+The owner can cancel a pending action at any time before execution:
+
+```move
+wrapper.cancel_schedule();
+```
+
+This clears the pending slot immediately, allowing a new action to be scheduled.
+
+## Putting it together
+
+Here is a protocol example that uses `delayed_transfer` to wrap its admin capability, ensuring any ownership change is visible on-chain for 24 hours before it takes effect:
+
+```move
+module my_sui_app::governed_protocol;
+
+use openzeppelin_access::delayed_transfer::{Self, DelayedTransferWrapper};
+use openzeppelin_math::rounding;
+use openzeppelin_math::u64 as math_u64;
+use sui::clock::Clock;
+
+const MIN_DELAY_MS: u64 = 86_400_000; // 24 hours
+const EMathOverflow: u64 = 0;
+
+public struct ProtocolAdmin has key, store {
+    id: UID,
+    fee_bps: u64,
+}
+
+/// Initialize: create the admin cap and wrap it with a 24-hour transfer delay.
+/// `delayed_transfer::wrap` transfers the wrapper to the deployer internally.
+fun init(ctx: &mut TxContext) {
+    let admin = ProtocolAdmin {
+        id: object::new(ctx),
+        fee_bps: 30, // 0.3%
+    };
+    delayed_transfer::wrap(admin, MIN_DELAY_MS, ctx.sender(), ctx);
+}
+
+/// Update the fee rate. Borrows the admin cap mutably without changing ownership.
+public fun update_fee(
+    wrapper: &mut DelayedTransferWrapper<ProtocolAdmin>,
+    new_fee_bps: u64,
+) {
+    let admin = delayed_transfer::borrow_mut(wrapper);
+    admin.fee_bps = new_fee_bps;
+}
+
+/// Compute a fee using the admin-configured rate and safe math.
+public fun compute_fee(
+    wrapper: &DelayedTransferWrapper<ProtocolAdmin>,
+    amount: u64,
+): u64 {
+    let admin = delayed_transfer::borrow(wrapper);
+    math_u64::mul_div(amount, admin.fee_bps, 10_000, rounding::up())
+        .destroy_or!(abort EMathOverflow)
+}
+
+/// Schedule a transfer to a new admin. Visible on-chain for 24 hours.
+public fun schedule_admin_transfer(
+    wrapper: &mut DelayedTransferWrapper<ProtocolAdmin>,
+    new_admin: address,
+    clock: &Clock,
+    ctx: &mut TxContext,
+) {
+    wrapper.schedule_transfer(new_admin, clock, ctx);
+}
+```
+
+This module combines both packages: `openzeppelin_math` for the fee calculation (explicit rounding, overflow handling) and `openzeppelin_access` for the ownership policy (24-hour delay, on-chain observability). Users monitoring the chain see the `TransferScheduled` event and can exit before a new admin takes over.
+
+Build and test:
+
+```bash
+sui move build
+sui move test
+```
 
 ## API Reference
 
-Use the full function-level reference here: [Access API](/contracts-sui/1.x/api/access).
+For function-level signatures and parameters, see the [Access API reference](/contracts-sui/1.x/api/access).
+
+## Next steps
+
+- [Access API reference](/contracts-sui/1.x/api/access) for full function signatures and error codes
+- [Integer Math](/contracts-sui/1.x/math) for safe arithmetic primitives used in protocol math
+- [Fixed-Point Math](/contracts-sui/1.x/fixed-point) for fractional values, prices, and signed deltas
+- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access) for inline documentation and implementation details
+- [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
+- [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/fixed-point.mdx b/content/contracts-sui/1.x/fixed-point.mdx
index 1449de91..8581edbd 100644
--- a/content/contracts-sui/1.x/fixed-point.mdx
+++ b/content/contracts-sui/1.x/fixed-point.mdx
@@ -2,10 +2,16 @@
 title: Fixed-Point Math
 ---
 
+<Callout type="warn">
+The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+</Callout>
+
 The `openzeppelin_fp_math` package adds two decimal fixed-point types with 9 decimals of precision, matching Sui's native coin precision (`10^9`). It is the right tool whenever you need real-valued arithmetic — prices, fees, rates, ratios, balance deltas — without giving up determinism or onchain auditability.
 
 The package complements `openzeppelin_math`, which covers integer arithmetic. Use `openzeppelin_math` when your values are whole numbers; reach for `openzeppelin_fp_math` when fractional values are part of the protocol.
 
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/fixed_point)
+
 ## Why a 9-decimal scale
 
 - Matches Sui's native coin decimals, so converting between token amounts and fixed-point values is straightforward.
@@ -17,6 +23,10 @@ The package complements `openzeppelin_math`, which covers integer arithmetic. Us
 - [`UD30x9`](/contracts-sui/1.x/api/fixed-point#ud30x9) — unsigned. Decimal range from `0` to roughly `3.4 × 10^29`.
 - [`SD29x9`](/contracts-sui/1.x/api/fixed-point#sd29x9) — signed (two's complement). Decimal range from roughly `-1.7 × 10^29` to `1.7 × 10^29`. Useful for balance deltas, signed adjustments, and any quantity that can dip below zero.
 
+The names encode the layout: `UD30x9` uses up to 30 integer digits with 9 fractional digits, `SD29x9` is the signed counterpart with one bit reserved for the sign. Both fit in 16 bytes of storage, so swapping `u128` for either type costs nothing in storage or arithmetic budget.
+
+Pick **`UD30x9`** for any quantity that cannot be negative: token balances, prices, fees, exchange rates, supply totals. Pick **`SD29x9`** when the value can dip below zero: balance deltas, signed adjustments, P&L, position sides.
+
 ## Usage
 
 Add the dependency in `Move.toml`:
@@ -32,14 +42,7 @@ Import the modules you need:
 use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
 ```
 
-## Casting vs converting
-
-Two distinct ways to move into and out of fixed-point form:
-
-- **Casting** — `wrap` / `unwrap` and cross-type casts. Preserves the underlying scaled bits. Use when the value is already in raw fixed-point form.
-- **Converting** — the `*_convert` modules. Applies or removes the `10^9` scale factor. Use when the input is a whole integer like `42` and you mean `42.0`.
-
-## Examples
+## Quickstart examples
 
 ### Build a fixed-point value from a whole integer
 
@@ -111,6 +114,375 @@ For `SD29x9` specifically, prefer `mod` (Euclidean, always non-negative) over `r
 `SD29x9::min()` is `-2^127`. There is no representable `+2^127`, so calling `abs` or `negate` on `min()` aborts with `EOverflow`. Same caveat for `wrap(_, true)` at maximum magnitude.
 </Callout>
 
+---
+
+## Why fixed-point on-chain
+
+Move has no native fractional type. Real-valued protocol math — prices, fees, interest rates, signed balance deltas — has to be encoded in integers. The naive approach is to scale by a power of two ("Q-notation": Q64.64, Q96, Q128, etc.) and use bit shifts. That works, but it has two persistent drawbacks:
+
+1. **Binary scales misalign with the units protocols actually report.** Token amounts, exchange rates, and oracle prices are quoted as decimals. Converting to and from a binary scale at every boundary creates rounding seams that are easy to get wrong and hard to audit.
+2. **Bit-shift arithmetic puts the rounding decision in the operator instead of the call site.** A `>>` is silent. A `mul_div`-shaped helper makes the rounding direction visible. The Cetus exploit hinged on a `checked_shl`-shaped function that silently passed a value it should have rejected; the same class of bug is harder to write when rounding is a named choice at every call site.
+
+`openzeppelin_fp_math` picks **decimal** fixed-point with **9 decimals** (`10^9`) — the same precision Sui uses for native coin amounts. `1.5` is `1_500_000_000`, `0.000_000_001` is `1`. Conversions between token amounts and fixed-point values become a single multiply or divide by `10^9`, with no bit-pattern reasoning involved.
+
+The package complements `openzeppelin_math`: integer arithmetic stays in `openzeppelin_math`, fractional arithmetic lives here. They use the same explicit-rounding philosophy.
+
+## Casting vs converting: the most important distinction
+
+The package draws a sharp line between two kinds of "convert this number to fixed-point" operations. Mixing them up is the most common way to introduce a `10^9`-sized bug, so it is worth getting clear on before writing any arithmetic.
+
+### Casting — preserves raw scaled bits
+
+Casting reinterprets a value that is **already in fixed-point form**. It does not multiply or divide by `10^9`.
+
+The core cast helpers live on the `sd29x9` and `ud30x9` modules:
+
+```move
+use openzeppelin_fp_math::{sd29x9, ud30x9};
+
+let one = ud30x9::wrap(1_000_000_000); // 1.0
+let raw = ud30x9::wrap(42);            // 0.000000042 — NOT 42.0
+
+let positive_one = sd29x9::wrap(1_000_000_000, false); // 1.0
+let small_negative = sd29x9::wrap(42, true);           // -0.000000042
+```
+
+Cross-type casts also count as casting: they preserve the scaled numeric meaning and only validate signedness or range.
+
+```move
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+
+let unsigned = ud30x9_convert::from_u128(42); // 42.0
+let signed = unsigned.into_SD29x9();          // 42.0 as SD29x9
+let roundtrip = signed.into_UD30x9();         // 42.0 as UD30x9
+```
+
+Use casting when your input is already fixed-point bits (e.g., loaded from storage, returned by another fixed-point function, or hand-encoded in a constant).
+
+### Converting — applies or removes the `10^9` scale
+
+Converting changes between **whole-integer** semantics and **fixed-point** semantics. Use the `*_convert` modules for this.
+
+```move
+use openzeppelin_fp_math::{sd29x9_convert, ud30x9_convert};
+
+let whole = ud30x9_convert::from_u128(42); // 42.0 — multiplies by 10^9
+let back = whole.to_u128_trunc();          // 42  — divides by 10^9, truncates fractional
+
+let delta = sd29x9_convert::from_u128(5, true); // -5.0
+let (magnitude, is_negative) = delta.to_parts_trunc();
+// magnitude == 5, is_negative == true
+```
+
+Use converting whenever the input or output represents a whole-number quantity in your domain (a token amount the user typed, a count, a percentage point).
+
+### The mental rule
+
+> If `42` means `42`, use `*_convert::from_u128` / `to_u*_trunc`.
+> If `42` means `0.000_000_042`, use `wrap` / `unwrap`.
+
+Mixing the two collapses to a `10^9` scale error somewhere downstream, usually far from where it was introduced.
+
+### Negative values: why the sign flag
+
+Move does not provide a native signed integer, so `SD29x9` conversions take an unsigned magnitude plus a `bool` sign flag. `to_parts_trunc` returns the same shape on the way out:
+
+```move
+use openzeppelin_fp_math::sd29x9_convert;
+
+// Build -5.0
+let neg_five = sd29x9_convert::from_u128(5, true);
+
+// Read it back as (magnitude, is_negative)
+let (mag, neg) = neg_five.to_parts_trunc();
+// mag == 5, neg == true
+```
+
+Two consequences worth knowing:
+
+1. `to_parts_trunc` always reports `is_negative = false` when the magnitude is zero, regardless of the underlying bit pattern. This avoids "negative zero" surprises in callers that branch on the flag.
+2. `to_u128_trunc` and `to_u64_trunc` abort on negative input. Use the `try_*` variants when you want a `none()` instead, or call `to_parts_trunc` to get sign and magnitude in one go.
+
+## Rounding direction in fixed-point arithmetic
+
+Like `openzeppelin_math`, this package treats rounding as a protocol decision. But the spelling is different: the rounding mode is encoded in the **function name**, not in a `RoundingMode` parameter.
+
+| Function pair | Rounding | When to use |
+|---|---|---|
+| `mul`, `mul_trunc` | toward zero | Default. The two are aliases — pick `mul_trunc` if you want the rounding direction visible at the call site. |
+| `mul_away` | away from zero | Fees, slippage caps, anywhere the protocol should never undercharge or under-reserve. |
+| `div`, `div_trunc` | toward zero | Default for division. Same alias relationship as `mul`. |
+| `div_away` | away from zero | When the divisor is user-supplied or quote-related and the protocol must bound itself conservatively. |
+
+The same vault-lifecycle logic from the integer-math guide applies here, just with finer granularity. If your vault holds `UD30x9` value internally:
+
+```move
+use openzeppelin_fp_math::ud30x9::UD30x9;
+
+/// Convert tokens to shares — round toward zero so the vault keeps the dust.
+public fun deposit_shares(amount: UD30x9, total_assets: UD30x9, total_supply: UD30x9): UD30x9 {
+    amount.mul_trunc(total_supply).div_trunc(total_assets)
+}
+
+/// Convert shares to tokens — round toward zero so the vault keeps the dust.
+public fun withdraw_assets(shares: UD30x9, total_assets: UD30x9, total_supply: UD30x9): UD30x9 {
+    shares.mul_trunc(total_assets).div_trunc(total_supply)
+}
+```
+
+Both directions truncate toward zero, so the vault never gives away fractional remainders. Flipping either to `mul_away` / `div_away` opens the same round-trip extraction attack discussed in the integer-math guide.
+
+### When `_trunc` and `_away` differ
+
+`mul` and `mul_trunc` differ only when the exact mathematical product cannot be represented in 9 decimals. For values that already fit cleanly, `mul_trunc(x, y) == mul_away(x, y)`. The choice only matters at the precision boundary — which, in fee-and-rate land, is exactly where it matters most.
+
+`div_away` is the helper you want for inverse-rate conversions. `1.0 / 3.0` is `0.333333333` with `div_trunc` and `0.333333334` with `div_away`. If your protocol owes the user some fraction of `x / 3`, rounding down on each individual settlement systematically under-pays the user.
+
+## Overflow and underflow
+
+Unlike `openzeppelin_math`, the fixed-point package does **not** return `Option<T>` from arithmetic. It aborts. The error constants come in three families:
+
+- **`EOverflow`** — the result exceeds the representable range of the target type.
+- **`EUnderflow`** — applies to `UD30x9::sub` only. Subtraction would produce a negative value, which is unrepresentable in an unsigned type.
+- **`EDivideByZero`** — applies to `div`, `div_trunc`, `div_away`, `mod`, and `rem`.
+
+There are also the unchecked-add and unchecked-subtract escape hatches, plus `unchecked_lshift` / `unchecked_rshift` on `UD30x9`. They wrap modulo `2^128` instead of aborting.
+
+```move
+use openzeppelin_fp_math::ud30x9;
+
+let a = ud30x9::max();
+let b = ud30x9_convert::from_u128(1);
+
+let bad = a.add(b);              // aborts with EOverflow
+let wrapped = a.unchecked_add(b); // wraps to a small value, no abort
+```
+
+Reach for `unchecked_*` only when you have already proved the operation is safe and want to skip the abort path (rare). For normal application code, prefer the checked versions and let aborts surface programmer bugs.
+
+If you need an `Option`-style API, build it locally:
+
+```move
+use openzeppelin_fp_math::ud30x9::UD30x9;
+
+public fun try_add(x: UD30x9, y: UD30x9): Option<UD30x9> {
+    let raw_sum = (x.unwrap() as u256) + (y.unwrap() as u256);
+    if (raw_sum > std::u128::max_value!() as u256) {
+        option::none()
+    } else {
+        option::some(ud30x9::wrap(raw_sum as u128))
+    }
+}
+```
+
+## Comparison and equality
+
+Comparison operators on `UD30x9` and `SD29x9` work how you would expect — `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `is_zero` — with one subtle point on the signed type:
+
+```move
+use openzeppelin_fp_math::sd29x9;
+
+let a = sd29x9::wrap(0, false);
+let b = sd29x9::wrap(0, true);
+// Both encode 0; eq compares raw bits, but `wrap` normalizes 0 magnitude to a single representation.
+let same = a.eq(b); // true
+```
+
+`SD29x9::wrap` rejects "negative zero" by mapping `(0, true)` and `(0, false)` to the same underlying bits, so equality on zeros behaves as expected. If you ever construct an `SD29x9` from raw bits via the package-internal `from_bits`, this normalization does not happen — but `from_bits` is not part of the public API surface, so most callers never encounter it.
+
+## Cross-type casts
+
+`UD30x9` and `SD29x9` represent the same scaled meaning when their values overlap in the non-negative range, so the package provides explicit casts both ways:
+
+```move
+use openzeppelin_fp_math::{sd29x9_convert, ud30x9_convert};
+
+// UD30x9 -> SD29x9
+let unsigned = ud30x9_convert::from_u128(42);   // 42.0 UD30x9
+let signed = unsigned.into_SD29x9();            // 42.0 SD29x9
+// `into_SD29x9` aborts with `ECannotBeConvertedToSD29x9` if the magnitude exceeds 2^127 - 1.
+
+// SD29x9 -> UD30x9
+let positive = sd29x9_convert::from_u128(42, false); // 42.0 SD29x9
+let back = positive.into_UD30x9();                   // 42.0 UD30x9
+// `into_UD30x9` aborts with `ECannotBeConvertedToUD30x9` if the value is negative.
+```
+
+Each direction has a `try_into_*` counterpart that returns `Option<T>` instead of aborting. Use the `try_*` variants on values that come from external input or untrusted callers; use the abort variants in internal protocol code where a failed cast is a program bug.
+
+## Bitwise operations on `UD30x9`
+
+`UD30x9` exposes a full set of bitwise helpers — `and`, `and2`, `or`, `xor`, `not`, plus `lshift` / `rshift` and their `unchecked_*` siblings. `SD29x9` does **not** expose bitwise operations, on purpose: bit-twiddling on a two's complement representation is rarely what protocol authors mean.
+
+The most common use for these is packing flags or scale-shifting raw bit patterns inside a fixed-point pipeline:
+
+```move
+use openzeppelin_fp_math::ud30x9;
+
+// Mask to keep only the low 64 bits of the raw representation.
+let truncated = ud30x9::wrap(some_value).and(0xFFFFFFFFFFFFFFFF);
+
+// Shift the raw representation right by 9 bits — note this is a bit shift,
+// not a divide-by-2^9, and not a divide-by-10^9.
+let shifted = ud30x9::wrap(some_value).rshift(9);
+```
+
+Two cautions:
+
+1. `lshift` aborts when shifting by `>= 128` bits or when the shift would consume non-zero high bits. `unchecked_lshift` truncates instead of aborting and returns `0` for `bits >= 128`.
+2. The bitwise operators work on **raw bits**, not on the decimal value. `x.lshift(1)` doubles the underlying `u128`, but it does **not** double the decimal value in any meaningful sense (you'd want `x.add(x)` for that).
+
+If you need a `*` 2 or `/` 2 operation, use arithmetic. The bitwise helpers are for explicit bit manipulation, not for fast arithmetic.
+
+## `pow`: useful but approximate
+
+Both types expose `pow(x, exp: u8)` for integer exponents. The implementation uses binary exponentiation with fixed-point multiplication, which means **every intermediate multiply applies a fixed-point truncation by `10^9`**.
+
+The consequences:
+
+- Results are biased toward zero. Rounding error compounds as `exp` grows.
+- For `0 < x < 1` (and the analogous range in `SD29x9`), intermediate values can reach zero before the final mathematically-correct result would.
+- Because truncation is applied at intermediate steps, fixed-point multiplication is **not associative under truncation**. The grouping that binary exponentiation uses can change the result.
+
+In practice:
+
+```move
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+
+let two = ud30x9_convert::from_u128(2);
+let eight = two.pow(3); // 8.0 — exact for whole-number bases.
+
+let half = ud30x9::wrap(500_000_000); // 0.5
+let q = half.pow(20); // ≈ 0.000000953... but truncation may bias the result.
+```
+
+For small integer exponents over operands that are not far from `1.0`, `pow` is fine. For long compounded products (interest accrual over many periods, statistical computations), prefer to:
+
+- Restructure the computation to reduce the number of intermediate truncations, or
+- Switch to a pre-computed lookup or higher-precision representation in the worst-case region, or
+- Bound the rounding error analytically and check whether your protocol can absorb it.
+
+## The `min()` gotcha on `SD29x9`
+
+`SD29x9::min()` returns `-2^127`. There is no representable `+2^127`, so several operations abort when called on `min()`:
+
+- `abs(min())` — aborts with `EOverflow`.
+- `negate(min())` — aborts with `EOverflow`.
+- `wrap(2^127, true)` is fine (it produces `min`); but `wrap(2^127, false)` aborts with `EOverflow`. There is no way to construct `min` via `wrap`; use `min()` directly.
+
+Most protocol code never sees `min()`. If your design naturally produces values near the signed-integer boundary, plan for it explicitly:
+
+```move
+use openzeppelin_fp_math::sd29x9;
+
+public fun safe_negate(x: sd29x9::SD29x9): sd29x9::SD29x9 {
+    if (x.eq(sd29x9::min())) {
+        // Domain decision: clamp, abort with a domain error, or saturate to max.
+        sd29x9::max()
+    } else {
+        x.negate()
+    }
+}
+```
+
+## `mod` vs `rem` on `SD29x9`
+
+`UD30x9::mod` is straightforward: it is the unsigned remainder, always non-negative. `SD29x9` exposes **two** remainder functions because the signed semantics differ:
+
+- **`rem(x, y)`** — truncating remainder. The magnitude is `abs(x) % abs(y)`, and the sign of the result follows the dividend `x`. `rem(-7, 3) = -1`.
+- **`mod(x, y)`** — Euclidean remainder. Always non-negative; satisfies `0 <= mod(x, y) < abs(y)`. `mod(-7, 3) = 2`.
+
+Most protocol code wants `mod` (Euclidean), because it gives a stable representative of the residue class regardless of the dividend's sign. `rem` is the right choice when you specifically want the remainder to follow the sign of the dividend (e.g., to preserve sign in a pipeline of signed adjustments).
+
+```move
+use openzeppelin_fp_math::sd29x9_convert;
+
+let dividend = sd29x9_convert::from_u128(7, true); // -7.0
+let divisor = sd29x9_convert::from_u128(3, false); // 3.0
+
+let r = dividend.rem(divisor); // -1.0
+let m = dividend.mod(divisor); //  2.0
+```
+
+Both abort with `EDivideByZero` if `y` is zero.
+
+## Putting it together
+
+Here is a pricing module example that combines several functions from the package:
+
+```move
+module my_sui_app::pricing;
+
+use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
+use openzeppelin_fp_math::ud30x9::UD30x9;
+
+const ONE_HUNDRED_PERCENT_BPS: u128 = 10_000;
+
+/// Apply a fee rate (in basis points) to an amount. Round away from zero
+/// so the protocol never undercharges.
+public fun apply_fee_bps(amount: UD30x9, fee_bps: u128): UD30x9 {
+    let bps_one = ud30x9_convert::from_u128(ONE_HUNDRED_PERCENT_BPS);
+    let fee = ud30x9_convert::from_u128(fee_bps);
+    amount.mul_away(fee).div_away(bps_one)
+}
+
+/// Quote a constant-product swap output, less a fee.
+public fun quote_swap_with_fee(
+    amount_in: UD30x9,
+    reserve_in: UD30x9,
+    reserve_out: UD30x9,
+    fee_bps: u128,
+): UD30x9 {
+    let fee = apply_fee_bps(amount_in, fee_bps);
+    let effective_in = amount_in.sub(fee);
+
+    // Constant-product output, rounded toward zero (in the user's favor as the
+    // taker, against the user as a fee recipient — model your protocol explicitly).
+    reserve_out.mul_trunc(effective_in).div_trunc(reserve_in.add(effective_in))
+}
+
+/// Settle a `UD30x9` quote into a whole `u64` token amount.
+public fun settle_to_u64(amount: UD30x9): u64 {
+    amount.to_u64_trunc()
+}
+```
+
+And the same pattern with signed deltas:
+
+```move
+module my_sui_app::ledger;
+
+use openzeppelin_fp_math::{sd29x9, sd29x9_convert};
+use openzeppelin_fp_math::sd29x9::SD29x9;
+
+/// Apply a signed adjustment to a running balance.
+public fun apply_delta(balance: SD29x9, magnitude: u128, is_negative: bool): SD29x9 {
+    let delta = sd29x9_convert::from_u128(magnitude, is_negative);
+    balance.add(delta)
+}
+
+/// Read out the absolute value as a positive UD30x9.
+public fun absolute(balance: SD29x9): ud30x9::UD30x9 {
+    balance.abs().into_UD30x9()
+}
+```
+
+Build and test:
+
+```bash
+sui move build
+sui move test
+```
+
 ## API Reference
 
-Use the full function-level reference here: [Fixed-Point Math API](/contracts-sui/1.x/api/fixed-point).
+For function-level signatures and parameters, see the [Fixed-Point Math API reference](/contracts-sui/1.x/api/fixed-point).
+
+## Next steps
+
+- [Fixed-Point Math API reference](/contracts-sui/1.x/api/fixed-point) for full function signatures
+- [Integer Math](/contracts-sui/1.x/math) for integer arithmetic primitives
+- [Access](/contracts-sui/1.x/access) for ownership-transfer policies on privileged capabilities
+- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/fixed_point) for inline documentation and implementation details
+- [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
+- [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/index.mdx b/content/contracts-sui/1.x/index.mdx
index 9bae3e79..37588ddd 100644
--- a/content/contracts-sui/1.x/index.mdx
+++ b/content/contracts-sui/1.x/index.mdx
@@ -2,9 +2,10 @@
 title: Contracts for Sui 1.x
 ---
 
-**OpenZeppelin Contracts for Sui v1.x** ships two core packages:
+**OpenZeppelin Contracts for Sui v1.x** ships three core packages:
 
-- `openzeppelin_math` for deterministic arithmetic, configurable rounding, and decimal scaling.
+- `openzeppelin_math` for deterministic integer arithmetic, configurable rounding, and decimal scaling.
+- `openzeppelin_fp_math` for 9-decimal fixed-point arithmetic (`UD30x9`, `SD29x9`) backed by `u128`.
 - `openzeppelin_access` for ownership-transfer wrappers around privileged `key + store` objects.
 
 ## Quickstart
@@ -27,16 +28,20 @@ cd my_sui_app
 ```bash
 mvr add @openzeppelin-move/access
 mvr add @openzeppelin-move/integer-math
+mvr add @openzeppelin-move/fixed-point-math
 ```
 
+You only need the dependencies your app actually uses — add what you need and drop the others.
+
 ### 3. Verify `Move.toml`
 
-`mvr add` updates `Move.toml` automatically. It should include:
+`mvr add` updates `Move.toml` automatically. With all three installed it should include:
 
 ```toml
 [dependencies]
 openzeppelin_access = { r.mvr = "@openzeppelin-move/access" }
 openzeppelin_math = { r.mvr = "@openzeppelin-move/integer-math" }
+openzeppelin_fp_math = { r.mvr = "@openzeppelin-move/fixed-point-math" }
 ```
 
 ### 4. Add a Minimal Module
@@ -53,7 +58,7 @@ use openzeppelin_math::u64::{mul_div, sqrt};
 
 public fun quote_with_fee(amount: u64): u64 {
     // 2.5% fee, rounded to nearest.
-    let quoted = mul_div(amount,1025u64, 1000u64, rounding::nearest());
+    let quoted = mul_div(amount, 1025u64, 1000u64, rounding::nearest());
     quoted.destroy_some()
 }
 
@@ -69,7 +74,15 @@ sui move build
 sui move test
 ```
 
+## Picking a package
+
+- Need integer arithmetic with safe overflow and explicit rounding? Use [Integer Math](/contracts-sui/1.x/math).
+- Need fractional values — prices, fees, rates, signed deltas? Use [Fixed-Point Math](/contracts-sui/1.x/fixed-point).
+- Need controlled transfer of admin/treasury/upgrade capabilities? Use [Access](/contracts-sui/1.x/access).
+
+The packages compose. A typical protocol module imports `openzeppelin_math` for share math, `openzeppelin_fp_math` for rate and fee math, and `openzeppelin_access` for the admin capability that governs both.
+
 ## Next Steps
 
-- Read package guides: [Integer Math](/contracts-sui/1.x/math), [Access](/contracts-sui/1.x/access).
-- Use API docs: [Integer Math](/contracts-sui/1.x/api/math), [Access](/contracts-sui/1.x/api/access).
+- Package guides: [Integer Math](/contracts-sui/1.x/math), [Fixed-Point Math](/contracts-sui/1.x/fixed-point), [Access](/contracts-sui/1.x/access).
+- API reference: [Integer Math](/contracts-sui/1.x/api/math), [Fixed-Point Math](/contracts-sui/1.x/api/fixed-point), [Access](/contracts-sui/1.x/api/access).
diff --git a/content/contracts-sui/1.x/learn/access-walkthrough.mdx b/content/contracts-sui/1.x/learn/access-walkthrough.mdx
deleted file mode 100644
index cb3bb287..00000000
--- a/content/contracts-sui/1.x/learn/access-walkthrough.mdx
+++ /dev/null
@@ -1,331 +0,0 @@
----
-title: Access Walkthrough
----
-
-<Callout type="warn">
-The example code snippets used within this walkthrough are experimental and have not been audited. They simply help exemplify the OpenZeppelin Sui package usage.
-</Callout>
-
-This guide provides a detailed walkthrough of the `openzeppelin_access` package. It explains the design behind each transfer policy, walks through the full lifecycle of wrapping and transferring capabilities, and covers the borrow patterns, events, and error handling you need to integrate these modules into a protocol. For a quick overview and getting-started examples, see the [Access package guide](https://docs.openzeppelin.com/contracts-sui/1.x/access). For function-level signatures, see the [Access API reference](https://docs.openzeppelin.com/contracts-sui/1.x/api/access).
-
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access)
-
----
-
-## Why controlled transfers matter
-
-On Sui, `sui::transfer::transfer` is instant and irreversible. There is no confirmation step, no waiting period, and no cancel mechanism. For everyday objects this is fine. For privileged capability objects, such as admin caps, treasury caps, or upgrade authorities, a single mistaken or malicious transfer permanently moves control with no recourse.
-
-The `openzeppelin_access` package adds two transfer policies that sit between you and that irreversible `transfer` call:
-
-| Module | What it enforces | Analogy from Solidity |
-| --- | --- | --- |
-| `two_step_transfer` | Recipient must explicitly accept before the transfer completes | `Ownable2Step` |
-| `delayed_transfer` | Mandatory time delay before execution; anyone can observe the pending action | `TimelockController` on ownership |
-
-If you already know which policy you need, skip to [Choosing a transfer policy](#choosing-a-transfer-policy) or jump directly to [two\_step\_transfer](#two_step_transfer) or [delayed\_transfer](#delayed_transfer).
-
----
-
-## Wrapping and transfer policies
-
-Both modules use the same underlying mechanism: wrapping a capability inside a new object that enforces a transfer policy on it.
-
-When you call `wrap`, the capability is stored as a dynamic object field inside the wrapper. This means:
-
-- **The wrapper becomes the custody object.** You hold the wrapper, not the capability directly. To transfer or recover the capability, you go through the wrapper's policy.
-- **The underlying capability retains its on-chain ID.** Off-chain indexers and explorers can still discover and track it via the dynamic object field. Wrapping does not make the capability invisible.
-- **The wrapper intentionally omits the `store` ability.** Without `store`, the wrapper cannot be moved via `transfer::public_transfer`. Only the module's own functions (which use the privileged `transfer::transfer` internally) can move it. This is a deliberate design choice that prevents accidental transfers outside the policy.
-
-A `WrapExecuted` event is emitted when a capability is wrapped, creating an on-chain record of when the policy was applied.
-
-### Borrowing without unwrapping
-
-Both modules provide three ways to use the wrapped capability without changing ownership:
-
-**Immutable borrow** for read-only access:
-
-```move
-let cap_ref = wrapper.borrow(); // &AdminCap
-```
-
-**Mutable borrow** for updating the capability's internal state:
-
-```move
-let cap_mut = wrapper.borrow_mut(); // &mut AdminCap
-```
-
-**Temporary move** for functions that require the capability by value. This uses the hot potato pattern: `borrow_val` returns a `Borrow` struct with no abilities (`copy`, `drop`, `store`, `key` are all absent). The Move compiler enforces that it must be consumed by `return_val` before the transaction ends.
-
-```move
-let (cap, borrow_token) = wrapper.borrow_val();
-
-/// Use cap in functions that require it by value.
-wrapper.return_val(cap, borrow_token); // compiler enforces this call
-```
-
-If you try to drop the borrow token, return a different capability, or return it to the wrong wrapper, the transaction either won't compile or will abort at runtime.
-
----
-
-## `two_step_transfer`
-
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/two_step.move)
-
-A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay, thus the transfer executes immediately once the recipient accepts.
-
-This is the right choice when the principal initiating the transfer is a known, controlled key (a multisig, a hot wallet operated by the same team) and the risk you are guarding against is sending the capability to a wrong or non-existent address, which would permanently lock the capability with no way to recover it.
-
-### Step 1: Wrap the capability
-
-```move
-module my_sui_app::admin;
-
-use openzeppelin_access::two_step_transfer;
-
-public struct AdminCap has key, store { id: UID }
-
-/// Wrap and immediately initiate a transfer to `new_admin`.
-/// The wrapper is consumed by `initiate_transfer` and held
-/// inside the shared `PendingOwnershipTransfer` until the
-/// recipient accepts or the initiator cancels.
-public fun wrap_and_transfer(cap: AdminCap, new_admin: address, ctx: &mut TxContext) {
-    let wrapper = two_step_transfer::wrap(cap, ctx);
-    // Emits WrapExecuted
-
-    wrapper.initiate_transfer(new_admin, ctx);
-    // Emits TransferInitiated
-}
-```
-
-`wrap` stores the `AdminCap` inside a `TwoStepTransferWrapper<AdminCap>` and emits a `WrapExecuted` event. Because the wrapper lacks the `store` ability, it cannot be sent via `transfer::public_transfer`. The intended next step is to call `initiate_transfer`, which consumes the wrapper and creates a shared `PendingOwnershipTransfer<AdminCap>` object that both parties can interact with.
-
-### Step 2: Initiate a transfer
-
-`initiate_transfer` consumes the wrapper by value and creates a shared `PendingOwnershipTransfer<AdminCap>` object. The sender's address is recorded as `from` (the cancel authority), and the recipient's address is recorded as `to`.
-
-```move
-/// Called by the current wrapper owner. Consumes the wrapper.
-wrapper.initiate_transfer(new_admin_address, ctx);
-/// Emits TransferInitiated { wrapper_id, from, to }
-```
-
-After this call, the wrapper is held inside the pending request via transfer-to-object. The original owner no longer has it in their scope, but they retain the ability to cancel because their address is recorded as `from`.
-
-The `TransferInitiated` event contains the pending request's ID and the wrapper ID, allowing off-chain indexers to discover the shared `PendingOwnershipTransfer` object for the next step.
-
-### Step 3: Recipient accepts (or initiator cancels)
-
-The designated recipient calls `accept_transfer` to complete the handoff. This step uses Sui's [transfer-to-object (TTO)](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) pattern: the wrapper was transferred to the `PendingOwnershipTransfer` object in Step 2, so the recipient must provide a `Receiving<TwoStepTransferWrapper<AdminCap>>` ticket to claim it. The `Receiving` type is Sui's mechanism for retrieving objects that were sent to another object rather than to a wallet.
-
-```move
-/// Called by the address recorded as `to` (new_admin_address).
-/// `request` is the shared PendingOwnershipTransfer<AdminCap> object.
-/// `wrapper_ticket` is the Receiving<TwoStepTransferWrapper<AdminCap>> for the wrapper
-/// that was transferred to the request object.
-two_step_transfer::accept_transfer(request, wrapper_ticket, ctx);
-// Emits TransferAccepted { wrapper_id, from, to }
-```
-
-If the initiator changes their mind before the recipient accepts, they can cancel. The cancel call also requires the `Receiving` ticket for the wrapper:
-
-```move
-/// Called by the address recorded as `from` (the original initiator).
-two_step_transfer::cancel_transfer(request, wrapper_ticket, ctx);
-/// Wrapper is returned to the `from` address.
-```
-
-### Unwrapping
-
-To permanently reclaim the raw capability and destroy the wrapper:
-
-```move
-let admin_cap = wrapper.unwrap(ctx);
-```
-
-This bypasses the transfer flow entirely. Only the current wrapper owner can call it.
-
-### Security note on shared-object flows
-
-`initiate_transfer` records `ctx.sender()` as the cancel authority. In normal single-owner usage, this is the wallet holding the wrapper. However, if `initiate_transfer` is called inside a shared-object executor where any user can be the transaction sender, a malicious user could call `initiate_transfer` targeting their own address as recipient. They would become both the pending recipient and the sole cancel authority, locking out the legitimate owner.
-
-Avoid using `two_step_transfer` in shared-object executor flows unless your design explicitly maps signer identity to cancel authority.
-
----
-
-## `delayed_transfer`
-
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/delayed.move)
-
-A transfer policy that enforces a configurable minimum delay between scheduling and executing a transfer. The delay is set at wrap time and cannot be changed afterward. This creates a publicly visible window before any authority change takes effect, giving monitoring systems, DAOs, and individual users time to detect and respond.
-
-This is the right choice when your protocol requires on-chain lead time before a capability changes hands, for example, to allow an incident response process to detect a compromised key, or to give depositors time to exit before governance parameters change.
-
-### Step 1: Wrap with a delay
-
-```move
-module my_sui_app::treasury;
-
-use openzeppelin_access::delayed_transfer;
-
-public struct TreasuryCap has key, store { id: UID }
-
-const MIN_DELAY_MS: u64 = 86_400_000; // 24 hours
-
-/// Creates the wrapper and transfers it to ctx.sender() internally
-public fun wrap_treasury_cap(cap: TreasuryCap, ctx: &mut TxContext) {
-    delayed_transfer::wrap(cap, MIN_DELAY_MS, ctx.sender(), ctx);
-}
-```
-
-`wrap` creates a `DelayedTransferWrapper<TreasuryCap>`, stores the capability inside it as a dynamic object field, and transfers the wrapper to the specified `recipient` (here, the caller). A `WrapExecuted` event is emitted. Unlike `two_step_transfer::wrap` which returns the wrapper, `delayed_transfer::wrap` handles the transfer internally and has no return value.
-
-### Step 2: Schedule a transfer
-
-```move
-/// Called by the current wrapper owner.
-wrapper.schedule_transfer(new_owner_address, &clock, ctx);
-/// Emits TransferScheduled with execute_after_ms = clock.timestamp_ms() + min_delay_ms
-```
-
-The `Clock` object is Sui's shared on-chain clock. The deadline is computed as `clock.timestamp_ms() + min_delay_ms` and stored in the wrapper. Only one action can be pending at a time; scheduling a second without canceling the first aborts with `ETransferAlreadyScheduled`.
-
-During the delay window, the `TransferScheduled` event is visible on-chain. Monitoring systems, governance dashboards, or individual users watching the chain can detect the pending transfer and take action (e.g., withdrawing funds from the protocol) before it executes.
-
-<Callout type="warn">
-The `recipient` in `schedule_transfer` must be a wallet address, not an object ID. If the wrapper is transferred to an object via transfer-to-object (TTO), both the wrapper and the capability inside it become permanently locked. The `delayed_transfer` module does not implement a `Receiving`-based retrieval mechanism, so there is no way to borrow, unwrap, or further transfer a wrapper that has been sent to an object. Always verify that the scheduled recipient is an address controlled by a keypair.
-</Callout>
-
-### Step 3: Wait, then execute
-
-```move
-/// Callable after the delay window has passed.
-wrapper.execute_transfer(&clock, ctx);
-/// Emits OwnershipTransferred. Consumes the wrapper and delivers it to the recipient.
-```
-
-`execute_transfer` consumes the wrapper by value. After this call, the wrapper has been transferred to the scheduled recipient and no longer exists in the caller's scope. Calling it before `execute_after_ms` aborts with `EDelayNotElapsed`.
-
-### Scheduling an unwrap
-
-The same delay enforcement applies to recovering the raw capability:
-
-```move
-/// Schedule the unwrap
-wrapper.schedule_unwrap(&clock, ctx);
-/// Emits UnwrapScheduled
-
-/// After the delay has elapsed, executes the unwrap: Emits UnwrapExecuted, wrapper is consumed, and capability is returned.
-let treasury_cap = wrapper.unwrap(&clock, ctx);
-```
-
-### Canceling
-
-The owner can cancel a pending action at any time before execution:
-
-```move
-wrapper.cancel_schedule();
-```
-
-This clears the pending slot immediately, allowing a new action to be scheduled.
-
----
-
-## Choosing a transfer policy
-
-**Use `two_step_transfer` when:**
-
-- The transfer can execute immediately once confirmed.
-- The principal initiating the transfer is a known, controlled key.
-- The risk you are guarding against is human error (wrong or non-existent address), not timing.
-
-**Use `delayed_transfer` when:**
-
-- Your protocol requires on-chain lead time before authority changes.
-- Users, DAOs, or monitoring systems need a window to detect and respond.
-- The delay should be a reliable, inspectable commitment visible to anyone.
-
-**Combining both:** The modules accept any `T: key + store`, so they compose. You could wrap a capability in `delayed_transfer` for the timing guarantee and use a `two_step_transfer` flow at the scheduling step for address-confirmation safety.
-
----
-
-## Putting it together
-
-Here is a protocol example that uses `delayed_transfer` to wrap its admin capability, ensuring any ownership change is visible on-chain for 24 hours before it takes effect:
-
-```move
-module my_sui_app::governed_protocol;
-
-use openzeppelin_access::delayed_transfer::{Self, DelayedTransferWrapper};
-use openzeppelin_math::rounding;
-use openzeppelin_math::u64 as math_u64;
-use sui::clock::Clock;
-
-const MIN_DELAY_MS: u64 = 86_400_000; // 24 hours
-const EMathOverflow: u64 = 0;
-
-public struct ProtocolAdmin has key, store {
-    id: UID,
-    fee_bps: u64,
-}
-
-/// Initialize: create the admin cap and wrap it with a 24-hour transfer delay.
-/// `delayed_transfer::wrap` transfers the wrapper to the deployer internally.
-fun init(ctx: &mut TxContext) {
-    let admin = ProtocolAdmin {
-        id: object::new(ctx),
-        fee_bps: 30, // 0.3%
-    };
-    delayed_transfer::wrap(admin, MIN_DELAY_MS, ctx.sender(), ctx);
-}
-
-/// Update the fee rate. Borrows the admin cap mutably without changing ownership.
-public fun update_fee(
-    wrapper: &mut DelayedTransferWrapper<ProtocolAdmin>,
-    new_fee_bps: u64,
-) {
-    let admin = delayed_transfer::borrow_mut(wrapper);
-    admin.fee_bps = new_fee_bps;
-}
-
-/// Compute a fee using the admin-configured rate and safe math.
-public fun compute_fee(
-    wrapper: &DelayedTransferWrapper<ProtocolAdmin>,
-    amount: u64,
-): u64 {
-    let admin = delayed_transfer::borrow(wrapper);
-    math_u64::mul_div(amount, admin.fee_bps, 10_000, rounding::up())
-        .destroy_or!(abort EMathOverflow)
-}
-
-/// Schedule a transfer to a new admin. Visible on-chain for 24 hours.
-public fun schedule_admin_transfer(
-    wrapper: &mut DelayedTransferWrapper<ProtocolAdmin>,
-    new_admin: address,
-    clock: &Clock,
-    ctx: &mut TxContext,
-) {
-    wrapper.schedule_transfer(new_admin, clock, ctx);
-}
-```
-
-This module combines both packages: `openzeppelin_math` for the fee calculation (explicit rounding, overflow handling) and `openzeppelin_access` for the ownership policy (24-hour delay, on-chain observability). Users monitoring the chain see the `TransferScheduled` event and can exit before a new admin takes over.
-
-Build and test:
-
-```bash
-sui move build
-sui move test
-```
-
----
-
-## Next steps
-
-- [Access package guide](https://docs.openzeppelin.com/contracts-sui/1.x/access) for a quick overview and examples
-- [Integer Math package guide](/contracts-sui/1.x/math) for a quick overview and examples
-- [Access API reference](https://docs.openzeppelin.com/contracts-sui/1.x/api/access) for full function signatures and error codes
-- [Math Walkthrough](/contracts-sui/1.x/learn/math-walkthrough) for a detailed walkthrough of the math library
-- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access) for inline documentation and implementation details
-- [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
-- [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/learn/index.mdx b/content/contracts-sui/1.x/learn/index.mdx
deleted file mode 100644
index 8b8908a4..00000000
--- a/content/contracts-sui/1.x/learn/index.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: Learn
----
-
-Comprehensive guides for building with OpenZeppelin Contracts for Sui.
-
-* [Math Walkthrough](/contracts-sui/1.x/learn/math-walkthrough) - A detailed walkthrough of the `openzeppelin_math` package: rounding modes, overflow handling, and safe arithmetic primitives
-* [Access Walkthrough](/contracts-sui/1.x/learn/access-walkthrough) - A detailed walkthrough of the `openzeppelin_access` package: two-step and delayed ownership transfer policies for privileged capabilities
diff --git a/content/contracts-sui/1.x/learn/math-walkthrough.mdx b/content/contracts-sui/1.x/learn/math-walkthrough.mdx
deleted file mode 100644
index ae77622e..00000000
--- a/content/contracts-sui/1.x/learn/math-walkthrough.mdx
+++ /dev/null
@@ -1,342 +0,0 @@
----
-title: Math Walkthrough
----
-
-<Callout type="warn">
-The example code snippets used within this walkthrough are experimental and have not been audited. They simply help exemplify the OpenZeppelin Sui Package usage.
-</Callout>
-
-This walkthrough provides a detailed walkthrough of the `openzeppelin_math` package. It is intended for developers who want to understand not just *what* each function does, but *when* and *why* to use it. For a quick overview and getting-started examples, see the [Integer Math package guide](https://docs.openzeppelin.com/contracts-sui/1.x/math). For function-level signatures and parameters, see the [Integer Math API reference](https://docs.openzeppelin.com/contracts-sui/1.x/api/math).
-
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core)
-
----
-
-## Why explicit math matters on-chain
-
-Move's native integer arithmetic aborts on overflow and truncates on division. Both behaviors are silent protocol decisions. An abort at an unexpected boundary can lock a transaction. A truncation that always rounds against your users creates a systematic value leak.
-
-In May 2025, a single flawed overflow check in a shared math library led to the Cetus exploit, where approximately $223 million was drained from the largest DEX on Sui. The bug was not in novel math. It was in a `checked_shl`-type function that silently passed a value it should have rejected, corrupting a fixed-point intermediate that multiple protocols depended on.
-
-`openzeppelin_math` addresses these problems by making every boundary decision explicit: rounding is a named parameter you pass in, overflow returns `Option<T>` that you then handle, and intermediate products are computed in wider types so they don't silently overflow before the final result is computed.
-
----
-
-## Rounding as a protocol decision
-
-The package guide introduces the three rounding modes (`Down`, `Up`, `Nearest`). Here we'll dig deeper into *why* this matters and how to think about rounding in practice.
-
-Every function that divides, shifts, or roots a value requires a `RoundingMode` argument. There is no default, and the choice is not cosmetic. Rounding direction determines which side of a transaction absorbs fractional remainders, and in modern day blockchain applications, that determines where value leaks.
-
-### The vault example
-
-Consider a vault that issues shares for deposits:
-
-```move
-use openzeppelin_math::{rounding, u64 as math_u64};
-
-const EMathOverflow: u64 = 0;
-
-/// Deposit: convert tokens to shares, rounding DOWN.
-/// The depositor receives slightly fewer shares than the exact ratio.
-/// The vault keeps the fractional remainder.
-public fun deposit_shares(amount: u64, total_assets: u64, total_supply: u64): u64 {
-    math_u64::mul_div(amount, total_supply, total_assets, rounding::down())
-		    .destroy_or!(abort EMathOverflow)
-}
-
-/// Withdrawal: convert shares to tokens, rounding DOWN.
-/// The withdrawer receives slightly fewer tokens than the exact ratio.
-/// The vault keeps the fractional remainder.
-public fun withdraw_assets(shares: u64, total_assets: u64, total_supply: u64): u64 {
-    math_u64::mul_div(shares, total_assets, total_supply, rounding::down())
-		    .destroy_or!(abort EMathOverflow)
-}
-```
-
-Both directions round down so the vault never gives away more than it holds. If you rounded up on deposits (giving the depositor extra shares) or up on withdrawals (giving the withdrawer extra tokens), an attacker could repeatedly deposit and withdraw small amounts, extracting the rounding remainder each time. Making rounding explicit in every call forces you to make this decision consciously and makes it visible in code review.
-
-### When to use each mode
-
-- **`rounding::down()`** rounds toward zero (truncation). Use when the caller should absorb the remainder. This is the safe default for most protocol-to-user calculations.
-- **`rounding::up()`** rounds away from zero (ceiling). Use when the protocol should absorb the remainder, or when you need a conservative upper bound.
-- **`rounding::nearest()`** rounds to the nearest integer, with ties rounded up (round-half-up). Use for fee quotes and display calculations where rounding against either party on non-tie values is undesirable.
-
----
-
-## Handling `Option<T>` at the boundary
-
-The package guide shows `Option<T>` returns briefly. Here we'll cover the patterns you'll use in practice.
-
-Every function whose result could exceed the type range returns `Option<T>`. This includes `mul_div`, `mul_shr`, `checked_shl`, `checked_shr`, and `inv_mod`. Functions that cannot overflow (`average`, `sqrt`, logarithms) return the value directly.
-
-### Pattern: abort with a domain-specific error
-
-The most common pattern. Define an error constant in your module and abort if the math overflows:
-
-```move
-use openzeppelin_math::rounding;
-use openzeppelin_math::u64::{mul_div};
-
-const EMathOverflow: u64 = 0;
-
-public fun compute_fee(amount: u64, fee_bps: u64): u64 {
-    mul_div(amount, fee_bps, 10_000u64, rounding::up())
-        .destroy_or!(abort EMathOverflow)
-}
-```
-
-### Pattern: fallback to a safe value
-
-Useful when overflow means "cap at maximum" rather than "this is an error":
-
-```move
-use openzeppelin_math::{rounding};
-use openzeppelin_math::u64::{mul_div};
-
-public fun capped_scale(value: u64, multiplier: u64): u64 {
-    let result = mul_div(value, multiplier, 1_000u64, rounding::down());
-    if (result.is_some()) {
-        result.destroy_some()
-    } else {
-        18_446_744_073_709_551_615u64 // u64::MAX
-    }
-}
-```
-
-### Pattern: propagate to the caller
-
-When your function is itself a building block, return `Option<T>` and let the caller decide:
-
-```move
-use openzeppelin_math::{rounding};
-use openzeppelin_math::u64::{mul_div};
-
-public fun try_compute_shares(amount: u64, total_assets: u64, total_supply: u64): Option<u64> {
-    mul_div(amount, total_supply, total_assets, rounding::down())
-}
-```
-
----
-
-## Core arithmetic: `mul_div`, `mul_shr`, `average`
-
-These three functions cover the fundamental operations behind swap pricing, fee calculations, interest accrual, and share-based accounting.
-
-<Callout>
-The functions shown in this walkthrough are simplified to illustrate their usage. In a real implementation, they must be defined within proper Move function syntax.
-</Callout>
-
-### `mul_div`
-
-Computes `(a * b) / denominator` with explicit rounding. The intermediate product is computed in a wider type (up to `u512` for `u256` inputs) so it never silently overflows. Returns `Option<T>`.
-
-```move
-use openzeppelin_math::{rounding, u256};
-use openzeppelin_math::u256::{mul_div};
-
-// Price calculation: (reserve_out * amount_in) / (reserve_in + amount_in)
-let output = mul_div(reserve_out, amount_in, reserve_in + amount_in, rounding::down());
-```
-
-Instead of carrying out any multiply-then-divide operation manually (e.g., `(a * b) / c`), you can simply use `mul_div` instead. The manual version overflows when `a * b` exceeds the type range, even if the final result after division would have been safe.
-
-### `mul_shr`
-
-Computes `(a * b) >> shift` with rounding. Equivalent to `mul_div` with a power-of-two denominator, but faster. Returns `Option<T>`.
-
-```move
-use openzeppelin_math::{rounding, u128};
-use openzeppelin_math::u128::{mul_shr};
-
-// Fixed-point multiplication: (price * quantity) / 2^64
-let result = mul_shr(price, quantity, 64u8, rounding::down());
-```
-
-Use `mul_shr` instead of `mul_div` when your denominator is a power of two. This is common in Q-notation fixed-point math (Q64.64, Q96, etc.) and the tick-math used in concentrated liquidity AMMs. The Cetus exploit involved exactly this class of operation.
-
-### `average`
-
-Computes the arithmetic mean of two values without overflow. Does not return `Option` since the result always fits in the input type.
-
-```move
-use openzeppelin_math::{rounding, u64};
-use openzeppelin_math::u64::{average};
-
-let midpoint = average(price_a, price_b, rounding::nearest());
-```
-
-A simple operation of `(a + b) / 2` overflows when both values are near the type maximum. `average` uses bit manipulation to avoid the intermediate sum entirely, making it safe regardless of input size. Use it for TWAP midpoints, interpolation, and any pairwise averaging.
-
----
-
-## Safe bit operations: `checked_shl`, `checked_shr`
-
-Move's standard shift operators silently discard bits. `checked_shl` and `checked_shr` return `None` if any non-zero bit would be lost.
-
-```move
-use openzeppelin_math::u64::{checked_shl};
-
-let scaled = checked_shl(1u64, 63u8);   // Some(9223372036854775808)
-let overflow = checked_shl(1u64, 64u8);  // None: bit pushed out
-```
-
-This is the exact vulnerability class behind the Cetus exploit: a function that checked for overflow on a left shift had an off-by-one in its threshold comparison, allowing a corrupted value through. `checked_shl` catches this by shifting left and then shifting back; if the round-trip doesn't preserve the original value, it returns `None`.
-
-Use these anywhere you are scaling values via bit shifts and need a guarantee that no data is silently discarded.
-
----
-
-## Introspection and logarithms
-
-These functions tell you about the structure of a number. They are used internally by the library and are useful in your own code for tick-math, encoding, and storage optimization.
-
-### `clz` and `msb`
-
-`clz` counts leading zero bits. `msb` returns the position of the most significant bit. Both return 0 for input 0.
-
-```move
-use openzeppelin_math::u64::{clz, msb};
-
-let leading_zeros = clz(256u64);  // 55 (bit 8 is set)
-let highest_bit = msb(256u64);    // 8
-```
-
-Use these when you need to know the minimum bit width required to represent a value: packing, encoding, or choosing a type width for further computation. Return types vary by module width (`u16` for `u256::clz`, `u8` for narrower types).
-
-### `log2`, `log10`, `log256`
-
-Integer logarithms with configurable rounding. All return 0 for input 0.
-
-```move
-use openzeppelin_math::{rounding};
-use openzeppelin_math::u256::{log2, log10, log256};
-
-let bits_needed = log2(1000u256, rounding::up());       // 10
-let decimal_digits = log10(1000u256, rounding::down());  // 3
-let bytes_needed = log256(1000u256, rounding::up());     // 2
-```
-
-**`log2`** is used in tick-math for concentrated liquidity AMMs, where price ranges map to integer ticks via a logarithmic function. Return type is `u16` for `u256`, `u8` for narrower types.
-
-**`log10`** appears in decimal-aware scaling and display formatting. Returns `u8` across all types.
-
-**`log256`** determines byte-length for encoding and serialization. Returns `u8` across all types.
-
-### `sqrt`
-
-Integer square root with configurable rounding. Returns 0 for input 0.
-
-```move
-use openzeppelin_math::{rounding};
-use openzeppelin_math::u256::{sqrt};
-
-let root_down = sqrt(10u256, rounding::down()); // 3
-let root_up =  sqrt(10u256, rounding::up());     // 4
-```
-
-Square roots appear in concentrated liquidity pricing (`sqrtPriceX96`), geometric mean oracles, and volatility calculations. Rounding direction matters: rounding the wrong way in a price calculation creates an exploitable discrepancy.
-
----
-
-## Modular arithmetic: `inv_mod`, `mul_mod`
-
-These functions operate in modular arithmetic, where values wrap around a modulus. They are essential for cryptographic verification, on-chain randomness schemes, and certain pricing algorithms.
-
-### `inv_mod`
-
-Returns the unique `x` where `value * x = 1 (mod modulus)` when the inputs are coprime. Returns `None` otherwise. Aborts if `modulus` is zero.
-
-```move
-use openzeppelin_math::u256::{inv_mod};
-
-let inv = inv_mod(19u256, 1_000_000_007u256);  // Some(157_894_738)
-let none = inv_mod(50u256, 100u256);            // None: not coprime
-```
-
-### `mul_mod`
-
-Multiplies two values modulo a modulus without intermediate overflow. Uses `u512` internally when both operands exceed `u128::MAX`.
-
-```move
-use openzeppelin_math::u256::{mul_mod};
-
-let product = mul_mod(a, b, 1_000_000_007u256);
-```
-
----
-
-## Decimal scaling
-
-When bridging between tokens with different decimal precisions, `decimal_scaling` handles the multiplier arithmetic safely: overflow-checked on upcasts, explicitly truncating on downcasts.
-
-```move
-use openzeppelin_math::decimal_scaling;
-
-// Convert a 6-decimal token amount to 9-decimal internal representation
-let scaled_up = decimal_scaling::safe_upcast_balance(amount, 6, 9);
-
-// Convert back, truncating any fractional remainder
-let scaled_down = decimal_scaling::safe_downcast_balance(amount_9, 9, 6);
-```
-
-`safe_downcast_balance` discards any fractional remainder in the lower digits. If your protocol must account for that remainder rather than silently dropping it, capture it before the downcast.
-
----
-
-## A note on `u512` and integer width
-
-The `openzeppelin_math` package includes a `u512` module that provides 512-bit unsigned integer operations. This module exists to make `u256` arithmetic consistent and overflow-safe. The per-width modules (`u64`, `u128`, `u256`) use `u512` internally for operations like `mul_div`, `mul_shr`, and `mul_mod` where intermediate products can exceed `u256`.
-
-For most protocol development on Sui, `u64` is the standard and recommended integer width. It is what the Sui framework uses for coin balances, timestamps, and gas accounting. Reach for `u128` or `u256` only when your domain genuinely requires wider values (e.g., high-precision fixed-point representations or cross-chain interoperability with systems that use 256-bit integers).
-
-`u512` is not intended for direct use in application code. If you find yourself reaching for it, consider whether the computation can be restructured to use `mul_div` or `mul_shr` on a narrower type instead, which handle the widening internally.
-
----
-
-## Putting it together
-
-Here is a pricing module example that combines several functions from the library:
-
-```move
-use openzeppelin_math::{rounding};
-use openzeppelin_math::u64::{mul_div, sqrt};
-
-const EMathOverflow: u64 = 0;
-
-/// Quote a swap output with a 0.25% fee, rounded to nearest.
-public fun quote_with_fee(amount_in: u64, reserve_in: u64, reserve_out: u64): u64 {
-    // Apply fee: amount_in * 997.5 / 1000 (approximated as 9975 / 10000)
-    let effective_in = mul_div(amount_in, 9975u64, 10000u64, rounding::down())
-        .destroy_or!(abort EMathOverflow);
-
-    // Constant-product swap output
-    mul_div(reserve_out, effective_in, reserve_in + effective_in, rounding::down())
-        .destroy_or!(abort EMathOverflow)
-}
-
-/// Geometric mean of two prices, rounded down.
-public fun geometric_mean(price_a: u64, price_b: u64): u64 {
-    let product = mul_div(price_a, price_b, 1u64, rounding::down())
-        .destroy_or!(abort EMathOverflow);
-    sqrt(product, rounding::down())
-}
-```
-
-Build and test:
-
-```bash
-sui move build
-sui move test
-```
-
----
-
-## Next steps
-
-- [Integer Math package guide](https://docs.openzeppelin.com/contracts-sui/1.x/math) for a quick overview and examples
-- [Integer Math API reference](https://docs.openzeppelin.com/contracts-sui/1.x/api/math) for full function signatures
-- [Access Walkthrough](/contracts-sui/1.x/learn/access-walkthrough) for the Access package walkthrough
-- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core) for inline documentation and implementation details
-- [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
-- [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/math.mdx b/content/contracts-sui/1.x/math.mdx
index e06aa072..cf97d073 100644
--- a/content/contracts-sui/1.x/math.mdx
+++ b/content/contracts-sui/1.x/math.mdx
@@ -2,10 +2,16 @@
 title: Integer Math
 ---
 
+<Callout type="warn">
+The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+</Callout>
+
 The `openzeppelin_math` package is the numeric foundation for OpenZeppelin Contracts for Sui. It provides deterministic arithmetic across unsigned integer widths, explicit rounding controls, and helpers for decimal normalization.
 
 Use this package when your app needs arithmetic behavior that is predictable, auditable, and safe around overflow and precision boundaries. Instead of hiding rounding and truncation inside implementation details, `openzeppelin_math` makes those decisions explicit so they can be part of your protocol rules.
 
+[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core)
+
 ## Usage
 
 Add the dependency in `Move.toml`:
@@ -21,7 +27,7 @@ Import the modules you need:
 use openzeppelin_math::{rounding, u64};
 ```
 
-## Examples
+## Quickstart examples
 
 ### Fee quote with explicit rounding
 
@@ -80,6 +86,313 @@ public fun scale_down_9_to_6(amount: u256): u64 {
 
 For prices, fees, ratios, and signed deltas, use the companion [Fixed-Point Math](/contracts-sui/1.x/fixed-point) package. It provides 9-decimal `UD30x9` and `SD29x9` types backed by `u128`, with the same explicit-rounding philosophy as the integer modules above.
 
+---
+
+## Why explicit math matters on-chain
+
+Move's native integer arithmetic aborts on overflow and truncates on division. Both behaviors are silent protocol decisions. An abort at an unexpected boundary can lock a transaction. A truncation that always rounds against your users creates a systematic value leak.
+
+In May 2025, a single flawed overflow check in a shared math library led to the Cetus exploit, where approximately $223 million was drained from the largest DEX on Sui. The bug was not in novel math. It was in a `checked_shl`-type function that silently passed a value it should have rejected, corrupting a fixed-point intermediate that multiple protocols depended on.
+
+`openzeppelin_math` addresses these problems by making every boundary decision explicit: rounding is a named parameter you pass in, overflow returns `Option<T>` that you then handle, and intermediate products are computed in wider types so they don't silently overflow before the final result is computed.
+
+## Rounding as a protocol decision
+
+Every function that divides, shifts, or roots a value requires a `RoundingMode` argument. There is no default, and the choice is not cosmetic. Rounding direction determines which side of a transaction absorbs fractional remainders, and in modern day blockchain applications, that determines where value leaks.
+
+### The vault example
+
+Consider a vault that issues shares for deposits:
+
+```move
+use openzeppelin_math::{rounding, u64 as math_u64};
+
+const EMathOverflow: u64 = 0;
+
+/// Deposit: convert tokens to shares, rounding DOWN.
+/// The depositor receives slightly fewer shares than the exact ratio.
+/// The vault keeps the fractional remainder.
+public fun deposit_shares(amount: u64, total_assets: u64, total_supply: u64): u64 {
+    math_u64::mul_div(amount, total_supply, total_assets, rounding::down())
+		    .destroy_or!(abort EMathOverflow)
+}
+
+/// Withdrawal: convert shares to tokens, rounding DOWN.
+/// The withdrawer receives slightly fewer tokens than the exact ratio.
+/// The vault keeps the fractional remainder.
+public fun withdraw_assets(shares: u64, total_assets: u64, total_supply: u64): u64 {
+    math_u64::mul_div(shares, total_assets, total_supply, rounding::down())
+		    .destroy_or!(abort EMathOverflow)
+}
+```
+
+Both directions round down so the vault never gives away more than it holds. If you rounded up on deposits (giving the depositor extra shares) or up on withdrawals (giving the withdrawer extra tokens), an attacker could repeatedly deposit and withdraw small amounts, extracting the rounding remainder each time. Making rounding explicit in every call forces you to make this decision consciously and makes it visible in code review.
+
+### When to use each mode
+
+- **`rounding::down()`** rounds toward zero (truncation). Use when the caller should absorb the remainder. This is the safe default for most protocol-to-user calculations.
+- **`rounding::up()`** rounds away from zero (ceiling). Use when the protocol should absorb the remainder, or when you need a conservative upper bound.
+- **`rounding::nearest()`** rounds to the nearest integer, with ties rounded up (round-half-up). Use for fee quotes and display calculations where rounding against either party on non-tie values is undesirable.
+
+## Handling `Option<T>` at the boundary
+
+Every function whose result could exceed the type range returns `Option<T>`. This includes `mul_div`, `mul_shr`, `checked_shl`, `checked_shr`, and `inv_mod`. Functions that cannot overflow (`average`, `sqrt`, logarithms) return the value directly.
+
+### Pattern: abort with a domain-specific error
+
+The most common pattern. Define an error constant in your module and abort if the math overflows:
+
+```move
+use openzeppelin_math::rounding;
+use openzeppelin_math::u64::{mul_div};
+
+const EMathOverflow: u64 = 0;
+
+public fun compute_fee(amount: u64, fee_bps: u64): u64 {
+    mul_div(amount, fee_bps, 10_000u64, rounding::up())
+        .destroy_or!(abort EMathOverflow)
+}
+```
+
+### Pattern: fallback to a safe value
+
+Useful when overflow means "cap at maximum" rather than "this is an error":
+
+```move
+use openzeppelin_math::{rounding};
+use openzeppelin_math::u64::{mul_div};
+
+public fun capped_scale(value: u64, multiplier: u64): u64 {
+    let result = mul_div(value, multiplier, 1_000u64, rounding::down());
+    if (result.is_some()) {
+        result.destroy_some()
+    } else {
+        18_446_744_073_709_551_615u64 // u64::MAX
+    }
+}
+```
+
+### Pattern: propagate to the caller
+
+When your function is itself a building block, return `Option<T>` and let the caller decide:
+
+```move
+use openzeppelin_math::{rounding};
+use openzeppelin_math::u64::{mul_div};
+
+public fun try_compute_shares(amount: u64, total_assets: u64, total_supply: u64): Option<u64> {
+    mul_div(amount, total_supply, total_assets, rounding::down())
+}
+```
+
+## Core arithmetic: `mul_div`, `mul_shr`, `average`
+
+These three functions cover the fundamental operations behind swap pricing, fee calculations, interest accrual, and share-based accounting.
+
+<Callout>
+The functions shown below are simplified to illustrate their usage. In a real implementation, they must be defined within proper Move function syntax.
+</Callout>
+
+### `mul_div`
+
+Computes `(a * b) / denominator` with explicit rounding. The intermediate product is computed in a wider type (up to `u512` for `u256` inputs) so it never silently overflows. Returns `Option<T>`.
+
+```move
+use openzeppelin_math::{rounding, u256};
+use openzeppelin_math::u256::{mul_div};
+
+// Price calculation: (reserve_out * amount_in) / (reserve_in + amount_in)
+let output = mul_div(reserve_out, amount_in, reserve_in + amount_in, rounding::down());
+```
+
+Instead of carrying out any multiply-then-divide operation manually (e.g., `(a * b) / c`), you can simply use `mul_div` instead. The manual version overflows when `a * b` exceeds the type range, even if the final result after division would have been safe.
+
+### `mul_shr`
+
+Computes `(a * b) >> shift` with rounding. Equivalent to `mul_div` with a power-of-two denominator, but faster. Returns `Option<T>`.
+
+```move
+use openzeppelin_math::{rounding, u128};
+use openzeppelin_math::u128::{mul_shr};
+
+// Fixed-point multiplication: (price * quantity) / 2^64
+let result = mul_shr(price, quantity, 64u8, rounding::down());
+```
+
+Use `mul_shr` instead of `mul_div` when your denominator is a power of two. This is common in Q-notation fixed-point math (Q64.64, Q96, etc.) and the tick-math used in concentrated liquidity AMMs. The Cetus exploit involved exactly this class of operation.
+
+### `average`
+
+Computes the arithmetic mean of two values without overflow. Does not return `Option` since the result always fits in the input type.
+
+```move
+use openzeppelin_math::{rounding, u64};
+use openzeppelin_math::u64::{average};
+
+let midpoint = average(price_a, price_b, rounding::nearest());
+```
+
+A simple operation of `(a + b) / 2` overflows when both values are near the type maximum. `average` uses bit manipulation to avoid the intermediate sum entirely, making it safe regardless of input size. Use it for TWAP midpoints, interpolation, and any pairwise averaging.
+
+## Safe bit operations: `checked_shl`, `checked_shr`
+
+Move's standard shift operators silently discard bits. `checked_shl` and `checked_shr` return `None` if any non-zero bit would be lost.
+
+```move
+use openzeppelin_math::u64::{checked_shl};
+
+let scaled = checked_shl(1u64, 63u8);   // Some(9223372036854775808)
+let overflow = checked_shl(1u64, 64u8);  // None: bit pushed out
+```
+
+This is the exact vulnerability class behind the Cetus exploit: a function that checked for overflow on a left shift had an off-by-one in its threshold comparison, allowing a corrupted value through. `checked_shl` catches this by shifting left and then shifting back; if the round-trip doesn't preserve the original value, it returns `None`.
+
+Use these anywhere you are scaling values via bit shifts and need a guarantee that no data is silently discarded.
+
+## Introspection and logarithms
+
+These functions tell you about the structure of a number. They are used internally by the library and are useful in your own code for tick-math, encoding, and storage optimization.
+
+### `clz` and `msb`
+
+`clz` counts leading zero bits. `msb` returns the position of the most significant bit. Both return 0 for input 0.
+
+```move
+use openzeppelin_math::u64::{clz, msb};
+
+let leading_zeros = clz(256u64);  // 55 (bit 8 is set)
+let highest_bit = msb(256u64);    // 8
+```
+
+Use these when you need to know the minimum bit width required to represent a value: packing, encoding, or choosing a type width for further computation. Return types vary by module width (`u16` for `u256::clz`, `u8` for narrower types).
+
+### `log2`, `log10`, `log256`
+
+Integer logarithms with configurable rounding. All return 0 for input 0.
+
+```move
+use openzeppelin_math::{rounding};
+use openzeppelin_math::u256::{log2, log10, log256};
+
+let bits_needed = log2(1000u256, rounding::up());       // 10
+let decimal_digits = log10(1000u256, rounding::down());  // 3
+let bytes_needed = log256(1000u256, rounding::up());     // 2
+```
+
+**`log2`** is used in tick-math for concentrated liquidity AMMs, where price ranges map to integer ticks via a logarithmic function. Return type is `u16` for `u256`, `u8` for narrower types.
+
+**`log10`** appears in decimal-aware scaling and display formatting. Returns `u8` across all types.
+
+**`log256`** determines byte-length for encoding and serialization. Returns `u8` across all types.
+
+### `sqrt`
+
+Integer square root with configurable rounding. Returns 0 for input 0.
+
+```move
+use openzeppelin_math::{rounding};
+use openzeppelin_math::u256::{sqrt};
+
+let root_down = sqrt(10u256, rounding::down()); // 3
+let root_up =  sqrt(10u256, rounding::up());     // 4
+```
+
+Square roots appear in concentrated liquidity pricing (`sqrtPriceX96`), geometric mean oracles, and volatility calculations. Rounding direction matters: rounding the wrong way in a price calculation creates an exploitable discrepancy.
+
+## Modular arithmetic: `inv_mod`, `mul_mod`
+
+These functions operate in modular arithmetic, where values wrap around a modulus. They are essential for cryptographic verification, on-chain randomness schemes, and certain pricing algorithms.
+
+### `inv_mod`
+
+Returns the unique `x` where `value * x = 1 (mod modulus)` when the inputs are coprime. Returns `None` otherwise. Aborts if `modulus` is zero.
+
+```move
+use openzeppelin_math::u256::{inv_mod};
+
+let inv = inv_mod(19u256, 1_000_000_007u256);  // Some(157_894_738)
+let none = inv_mod(50u256, 100u256);            // None: not coprime
+```
+
+### `mul_mod`
+
+Multiplies two values modulo a modulus without intermediate overflow. Uses `u512` internally when both operands exceed `u128::MAX`.
+
+```move
+use openzeppelin_math::u256::{mul_mod};
+
+let product = mul_mod(a, b, 1_000_000_007u256);
+```
+
+## Decimal scaling
+
+When bridging between tokens with different decimal precisions, `decimal_scaling` handles the multiplier arithmetic safely: overflow-checked on upcasts, explicitly truncating on downcasts.
+
+```move
+use openzeppelin_math::decimal_scaling;
+
+// Convert a 6-decimal token amount to 9-decimal internal representation
+let scaled_up = decimal_scaling::safe_upcast_balance(amount, 6, 9);
+
+// Convert back, truncating any fractional remainder
+let scaled_down = decimal_scaling::safe_downcast_balance(amount_9, 9, 6);
+```
+
+`safe_downcast_balance` discards any fractional remainder in the lower digits. If your protocol must account for that remainder rather than silently dropping it, capture it before the downcast.
+
+## A note on `u512` and integer width
+
+The `openzeppelin_math` package includes a `u512` module that provides 512-bit unsigned integer operations. This module exists to make `u256` arithmetic consistent and overflow-safe. The per-width modules (`u64`, `u128`, `u256`) use `u512` internally for operations like `mul_div`, `mul_shr`, and `mul_mod` where intermediate products can exceed `u256`.
+
+For most protocol development on Sui, `u64` is the standard and recommended integer width. It is what the Sui framework uses for coin balances, timestamps, and gas accounting. Reach for `u128` or `u256` only when your domain genuinely requires wider values (e.g., high-precision fixed-point representations or cross-chain interoperability with systems that use 256-bit integers).
+
+`u512` is not intended for direct use in application code. If you find yourself reaching for it, consider whether the computation can be restructured to use `mul_div` or `mul_shr` on a narrower type instead, which handle the widening internally.
+
+## Putting it together
+
+Here is a pricing module example that combines several functions from the library:
+
+```move
+use openzeppelin_math::{rounding};
+use openzeppelin_math::u64::{mul_div, sqrt};
+
+const EMathOverflow: u64 = 0;
+
+/// Quote a swap output with a 0.25% fee, rounded to nearest.
+public fun quote_with_fee(amount_in: u64, reserve_in: u64, reserve_out: u64): u64 {
+    // Apply fee: amount_in * 997.5 / 1000 (approximated as 9975 / 10000)
+    let effective_in = mul_div(amount_in, 9975u64, 10000u64, rounding::down())
+        .destroy_or!(abort EMathOverflow);
+
+    // Constant-product swap output
+    mul_div(reserve_out, effective_in, reserve_in + effective_in, rounding::down())
+        .destroy_or!(abort EMathOverflow)
+}
+
+/// Geometric mean of two prices, rounded down.
+public fun geometric_mean(price_a: u64, price_b: u64): u64 {
+    let product = mul_div(price_a, price_b, 1u64, rounding::down())
+        .destroy_or!(abort EMathOverflow);
+    sqrt(product, rounding::down())
+}
+```
+
+Build and test:
+
+```bash
+sui move build
+sui move test
+```
+
 ## API Reference
 
-Use the full function-level reference here: [Integer Math API](/contracts-sui/1.x/api/math).
+For function-level signatures and parameters, see the [Integer Math API reference](/contracts-sui/1.x/api/math).
+
+## Next steps
+
+- [Integer Math API reference](/contracts-sui/1.x/api/math) for full function signatures
+- [Fixed-Point Math](/contracts-sui/1.x/fixed-point) for fractional values, prices, and signed deltas
+- [Access](/contracts-sui/1.x/access) for ownership-transfer policies on privileged capabilities
+- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core) for inline documentation and implementation details
+- [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
+- [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/index.mdx b/content/contracts-sui/index.mdx
index 038dfaf9..a045cc1f 100644
--- a/content/contracts-sui/index.mdx
+++ b/content/contracts-sui/index.mdx
@@ -12,19 +12,19 @@ import { latestStable } from "./latest-versions.js";
   <Card href={`/contracts-sui/${latestStable}`} title={`Overview (${latestStable})`}>
     Install packages, set up a Move project, and run a first end-to-end integration.
   </Card>
-  <Card href={`/contracts-sui/${latestStable}/learn`} title="Learn">
-    In-depth walkthroughs covering safe arithmetic, rounding, overflow handling, and ownership transfer policies.
-  </Card>
 </Cards>
 
 ## Packages
 
 <Cards>
   <Card href={`/contracts-sui/${latestStable}/math`} title="Integer Math">
-    Package-level guide for math primitives, including intent, module map, and usage boundaries.
+    Deterministic integer arithmetic with explicit rounding, overflow-safe `mul_div`/`mul_shr`, and decimal scaling helpers.
+  </Card>
+  <Card href={`/contracts-sui/${latestStable}/fixed-point`} title="Fixed-Point Math">
+    9-decimal fixed-point types (`UD30x9`, `SD29x9`) for prices, fees, rates, and signed balance deltas.
   </Card>
   <Card href={`/contracts-sui/${latestStable}/access`} title="Access">
-    Package-level guide for access primitives, including transfer policy selection and safety models.
+    Ownership-transfer policies (`two_step_transfer`, `delayed_transfer`) for privileged capabilities.
   </Card>
 </Cards>
 
@@ -32,7 +32,10 @@ import { latestStable } from "./latest-versions.js";
 
 <Cards>
   <Card href={`/contracts-sui/${latestStable}/api/math`} title="Integer Math">
-    Explore the complete math API, including all functions and types.
+    Explore the complete integer math API, including all functions and types.
+  </Card>
+  <Card href={`/contracts-sui/${latestStable}/api/fixed-point`} title="Fixed-Point Math">
+    Explore the complete fixed-point math API, including the `UD30x9` and `SD29x9` types and their arithmetic, comparison, and conversion modules.
   </Card>
   <Card href={`/contracts-sui/${latestStable}/api/access`} title="Access">
     Explore the complete access API reference, including module-level functions, core types, emitted events, and expected error conditions for integration.
diff --git a/skills/docs-sync/SKILL.md b/skills/docs-sync/SKILL.md
index 2298c15d..b38855cd 100644
--- a/skills/docs-sync/SKILL.md
+++ b/skills/docs-sync/SKILL.md
@@ -1,6 +1,61 @@
 ---
 name: docs-sync
-description: Update the centralized OpenZeppelin docs repo after a smart contracts library changes. Use after a contracts release, a merged PR in a contracts library, or any time you need to bring a docs slice (library + version) back in line with the contracts repo. The skill takes two contract commits (BASE_COMMIT, HEAD_COMMIT) as the source of truth and produces docs edits that follow the Diátaxis framework. Trigger on phrases like "sync docs for contracts-sui", "update docs after the contracts PR", "regenerate API reference for v1.x", "docs-sync".
+description: Use this skill to update the centralized OpenZeppelin docs repo after a smart contracts library changes. Trigger after a contracts release, a merged PR in a contracts library, or any time a docs slice (library + version) needs to be brought back in line with the contracts repo. The skill takes two contract commits (BASE_COMMIT, HEAD_COMMIT) as the source of truth and produces docs edits that follow the Diátaxis framework. Use whenever the user says "sync docs for contracts-sui", "update docs after the contracts PR", "regenerate API reference for v1.x", or "docs-sync".
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+inputs:
+  mode:
+    type: choice
+    prompt: "Run mode. interactive shows structured proposals at each gate and waits for approval; automatic infers from config and runs end-to-end without prompts."
+    options:
+      - interactive
+      - automatic
+    default: interactive
+    required: false
+  contracts_repo_path:
+    type: text
+    prompt: "Absolute filesystem path to the contracts repo (the source of truth). Must be a git repo, must NOT be the same as the docs repo."
+    required: true
+  docs_repo_path:
+    type: text
+    prompt: "Absolute filesystem path to the docs repo (where edits will land). Leave blank to use the current working directory."
+    required: false
+  base_commit:
+    type: text
+    prompt: "BASE_COMMIT — git SHA, tag, or ref in the contracts repo marking the START of the diff (typically the previous release tag)."
+    required: true
+  head_commit:
+    type: text
+    prompt: "HEAD_COMMIT — git SHA, tag, or ref in the contracts repo marking the END of the diff (typically the new release tag, or HEAD)."
+    required: true
+  library_id:
+    type: text
+    prompt: "LIBRARY_ID — the docs slice to update (e.g., contracts-sui). Must match a config file at skills/docs-sync/config/libraries/<library_id>.yml."
+    required: true
+  docs_version:
+    type: text
+    prompt: "DOCS_VERSION — the version directory inside the slice to edit (e.g., 1.x)."
+    required: true
+  release_version:
+    type: text
+    prompt: "RELEASE_VERSION — the contracts release tag this sync targets (e.g., v1.2.0). Used for source-link version pins and release notes."
+    required: true
+  docs_update_scope:
+    type: choice
+    prompt: "Scope of docs to update. full = everything the matrix requires; api-only = API reference + nav + source links only; guides-only = guides/tutorials/explanations + snippets only."
+    options:
+      - full
+      - api-only
+      - guides-only
+    default: full
+    required: false
+  target_audience:
+    type: text
+    prompt: "TARGET_AUDIENCE override. Leave blank to use the value in the slice config."
+    required: false
+  docs_tone:
+    type: text
+    prompt: "DOCS_TONE override. Leave blank to use the value in the slice config."
+    required: false
 ---
 
 # docs-sync
@@ -22,22 +77,33 @@ Do **not** trigger this skill for:
 - Pure docs cleanup unrelated to contracts changes (use a regular edit).
 - Changes that have not yet landed in a commit on the contracts repo.
 
-## Required runtime inputs
-
-The skill needs the inputs listed below. Callers may pre-supply any of
-them in the invocation prompt; whatever is missing is collected
-interactively in **Step 0** of `process.md` via `AskUserQuestion`. In
-`automatic` mode, missing required inputs are a hard failure — the
-skill will not invent SHAs, paths, or versions.
-
-Required: `<MODE>`, `<CONTRACTS_REPO_PATH>`, `<DOCS_REPO_PATH>`,
-`<BASE_COMMIT>`, `<HEAD_COMMIT>`, `<LIBRARY_ID>`, `<DOCS_VERSION>`,
-`<RELEASE_VERSION>`, `<DOCS_UPDATE_SCOPE>` (default `full`).
-
-Optional: `<TARGET_AUDIENCE>`, `<DOCS_TONE>`.
-
-See `process.md` Step 0 for defaults, prompt templates, and inline
-validation rules.
+## Inputs
+
+All required inputs are declared in the frontmatter `inputs` schema and
+gathered by the harness before the skill body runs. The skill body must
+not prompt for inputs interactively; if a required input is missing or
+fails validation, return a clear error message that names the field and
+let the caller re-invoke.
+
+The full input set is:
+
+| Input                | Required | Notes                                            |
+|----------------------|----------|--------------------------------------------------|
+| `mode`               | no       | `interactive` (default) or `automatic`           |
+| `contracts_repo_path`| yes      | absolute path; must be a git repo                |
+| `docs_repo_path`     | no       | defaults to current working directory            |
+| `base_commit`        | yes      | git SHA / tag / ref in the contracts repo        |
+| `head_commit`        | yes      | git SHA / tag / ref in the contracts repo        |
+| `library_id`         | yes      | must have `config/libraries/<library_id>.yml`    |
+| `docs_version`       | yes      | e.g. `1.x`                                       |
+| `release_version`    | yes      | e.g. `v1.2.0`                                    |
+| `docs_update_scope`  | no       | `full` (default), `api-only`, `guides-only`      |
+| `target_audience`    | no       | overrides config                                 |
+| `docs_tone`          | no       | overrides config                                 |
+
+`process.md` Step 0 validates these and applies safe defaults. In
+`automatic` mode, missing or invalid required inputs are a hard failure
+— never invent SHAs, paths, or versions.
 
 ## Source-of-truth constraint
 
@@ -56,23 +122,42 @@ of truth:
 - PR descriptions or commit messages.
 - Informal change summaries.
 
-## Mode selection
+## Mode behavior
+
+- **interactive**: Runs through structured proposal gates (see below).
+  Stops after each gate and waits for the user to approve, refine, or
+  reject the plan. API reference edits within an approved plan proceed
+  deterministically; broad guide/tutorial/explanation rewrites need
+  per-page approval.
+- **automatic**: Skips all gates. Applies every matrix-required update
+  within scope, records every assumption in the report. If a required
+  decision cannot be inferred safely, stops or records
+  `needs-human-review` rather than fabricating content.
 
-1. If the caller passed `<MODE>`, use it.
-2. Otherwise read `automation.default_mode` from config
-   (`skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`).
-3. Otherwise default to `interactive`.
+## Interactive gates
 
-- **interactive**: summarize and classify first. Ask only questions that
-  change scope, examples, release notes, audience, or security framing.
-  API reference edits may proceed deterministically; broad guide,
-  tutorial, or explanation rewrites need confirmation.
-- **automatic**: ask no questions. Infer from config and sibling pages,
-  apply all required matrix updates within scope, and record assumptions.
-  If a required decision cannot be inferred safely, stop or leave a
-  `needs-human-review` finding instead of fabricating content.
+Interactive runs **MUST** stop at each of the following gates and wait
+for explicit user approval before continuing. The skill does this by
+emitting a structured proposal block and ending its turn — the user's
+next message is the approval (or refinement). Do not use `AskUserQuestion` or any other interactive tool at any gate; gates are pure text + end-of-turn.
 
-## Scope selection
+| Gate                      | Stop point             | What is shown                                                                              |
+|---------------------------|------------------------|--------------------------------------------------------------------------------------------|
+| **G1 — Inputs & config**  | after Step 2           | resolved inputs, slice paths, automation defaults; flag missing/odd values                 |
+| **G2 — Public API delta** | after Step 9           | added / removed / changed modules, functions, structs, events, errors with signatures      |
+| **G3 — Docs edit plan**   | after Step 11          | every doc file to be **created**, **edited**, or **deleted**, grouped by category, with the API items each one covers and matrix-required pages that are out of scope |
+| **G4 — Per-page rewrites**| before each broad rewrite in Step 13 | the file path, the sections to be rewritten, and the rationale (Diátaxis category, matrix row) |
+
+Each proposal block uses the templates in `references/proposals/` (see
+that directory's `README.md`). Approval phrases the skill should accept:
+"approve", "looks good", "proceed", "yes". Anything else is treated as a
+refinement — apply the requested changes, re-emit the proposal, and wait
+again.
+
+In `automatic` mode, gates are skipped and the proposal contents are
+written to the final report instead.
+
+## Scope behavior
 
 - `full`: apply the full matrix.
 - `api-only`: update API reference, source links, stale identifiers in
@@ -81,16 +166,16 @@ of truth:
 - `guides-only`: update guides, tutorials, explanations, and snippets.
   Still inspect the API diff so stale prose can be found, but do not
   regenerate reference pages.
-- `targeted:<paths>`: edit only the listed docs paths plus required
-  navigation changes for those paths. Report every matrix-required
-  update outside the target set as skipped.
+
+(Targeted scope by path list is not exposed as an input; if a caller
+needs it, they can refine the G3 plan before approving.)
 
 ## Config memory
 
 Always load:
 
 ```
-skills/docs-sync/config/libraries/<LIBRARY_ID>.yml
+skills/docs-sync/config/libraries/<library_id>.yml
 ```
 
 This file is committed to the docs repo and is the canonical source of
@@ -107,22 +192,24 @@ generated docs.
 Read only what the run needs:
 
 1. `process.md` — the deterministic end-to-end workflow.
-2. `references/rules/change-classification.md` — how to classify each
+2. `references/proposals/` — proposal-block templates for the G1–G4 gates.
+3. `references/rules/change-classification.md` — how to classify each
    contract change.
-3. `references/rules/doc-update-matrix.md` — what docs each change type
+4. `references/rules/doc-update-matrix.md` — what docs each change type
    forces.
-4. `references/rules/api-reference-rules.md` — required for API
+5. `references/rules/api-reference-rules.md` — required for API
    reference updates.
-5. `references/rules/diataxis-rules.md` — required when creating or reshaping tutorial,
-   guide, explanation, or reference content.
-6. Templates under `references/templates/` — only when creating new
+6. `references/rules/diataxis-rules.md` — required when creating or
+   reshaping tutorial, guide, explanation, or reference content.
+7. Templates under `references/templates/` — only when creating new
    pages or replacing a broken structure.
-7. `references/rules/docs-pr-checklist.md` and
+8. `references/rules/docs-pr-checklist.md` and
    `references/reports/docs-sync-report-template.md` — final validation
    and summary.
 
-Use the validation specs under `references/checks/` as check definitions. They are
-not executable scripts unless later replaced with real tooling.
+Use the validation specs under `references/checks/` as check
+definitions. They are not executable scripts unless later replaced with
+real tooling.
 
 ## Scope of edits
 
diff --git a/skills/docs-sync/process.md b/skills/docs-sync/process.md
index f77fdc80..72c4a08a 100644
--- a/skills/docs-sync/process.md
+++ b/skills/docs-sync/process.md
@@ -7,149 +7,125 @@ skipping ahead.
 All paths in this document are relative to `<DOCS_REPO_PATH>` unless
 explicitly prefixed with `<CONTRACTS_REPO_PATH>`.
 
----
-
-## Step 0 — Collect runtime inputs
+In `interactive` mode, the workflow stops at four gates (G1–G4) and
+waits for explicit user approval. The skill MUST emit a structured
+proposal block (templates under `references/proposals/`) and end its
+turn at each gate. The skill MUST NOT call `AskUserQuestion` or any
+other interactive tool — inputs are gathered by the harness from the
+frontmatter `inputs` schema before this process starts. In `automatic`
+mode, every gate is skipped and its proposal contents are appended to
+the final report.
 
-Inputs may arrive in two ways:
+---
 
-1. **Pre-supplied** in the invocation prompt (`LIBRARY_ID=contracts-sui`,
-   `BASE_COMMIT=abc123`, etc.).
-2. **Collected interactively** here, using the `AskUserQuestion` tool,
-   for any required input the caller did not supply.
+## Step 0 — Validate runtime inputs
 
-Required inputs (see SKILL.md for full list): `<MODE>`,
-`<CONTRACTS_REPO_PATH>`, `<DOCS_REPO_PATH>`, `<BASE_COMMIT>`,
-`<HEAD_COMMIT>`, `<LIBRARY_ID>`, `<DOCS_VERSION>`, `<RELEASE_VERSION>`,
-`<DOCS_UPDATE_SCOPE>`.
+Inputs arrive from the frontmatter `inputs` schema (the harness gathers
+them upfront). Step 0 validates them and applies safe defaults — it
+does not prompt the user.
 
-### 0.1 Resolve from caller args and defaults first
+### 0.1 Apply defaults
 
-Before prompting, fill in what can be inferred without the user:
+For each input that arrived empty, apply:
 
-- `<DOCS_REPO_PATH>`: default to the current working directory if it is
-  the docs repo (verify by checking for `skills/docs-sync/SKILL.md`).
-- `<LIBRARY_ID>`: if exactly one file exists under
-  `skills/docs-sync/config/libraries/*.yml`, use that slice id.
-- `<DOCS_VERSION>`: if the resolved slice has exactly one version
-  directory under `docs.version_root`'s parent, use that.
-- `<DOCS_UPDATE_SCOPE>`: default to `full` unless the caller scoped it.
-- `<MODE>`: if not supplied, read `automation.default_mode` from the
-  resolved config; otherwise default to `interactive`.
+- `mode`: read `automation.default_mode` from the resolved slice config
+  if present; otherwise `interactive`.
+- `docs_repo_path`: current working directory, **only if** it is the
+  docs repo (verify by checking that `skills/docs-sync/SKILL.md` exists
+  inside it). Otherwise this is a hard error.
+- `docs_update_scope`: `full`.
+- `target_audience` / `docs_tone`: read from slice config; do not invent
+  values.
 
-Record every default that was applied so the final report can list them
-as assumptions.
+Record every default that was applied so the G1 proposal and the final
+report can list them as assumptions.
 
-### 0.2 If `<MODE>` resolves to `automatic`, do not prompt
+### 0.2 Validate
 
-In `automatic` mode, missing required inputs are a hard failure. Stop
-with a clear message naming the missing fields. Do not invent SHAs,
-versions, or paths.
+For each input, validate inline. On failure, **stop** and return a
+single error message that names every failing field — do not partially
+proceed.
 
-### 0.3 Otherwise, prompt for missing inputs
+- `contracts_repo_path` exists and is a git repo:
+  `git -C <CONTRACTS_REPO_PATH> rev-parse --is-inside-work-tree`.
+- `docs_repo_path` exists and is a git repo.
+- `contracts_repo_path` is **not** the same path as `docs_repo_path`.
+- `library_id` has a config file at
+  `skills/docs-sync/config/libraries/<library_id>.yml`.
+- `base_commit` and `head_commit` resolve in the contracts repo:
+  `git -C <CONTRACTS_REPO_PATH> rev-parse --verify <SHA>^{commit}`.
 
-For each input still missing, ask the user via `AskUserQuestion`. Group
-related inputs into a single call (the tool accepts up to 4 questions
-per call). Use the templates below.
+In `automatic` mode, any validation failure is a hard error — never
+invent SHAs, paths, or versions.
 
-**Bounded inputs — multiple choice** (let the user pick "Other" only
-when the listed options truly do not fit):
+In `interactive` mode, the validation error is the response — the user
+re-invokes with corrected inputs. The skill MUST NOT retry on its own.
 
-- `<MODE>`: options `interactive` (Recommended) and `automatic`.
-- `<DOCS_UPDATE_SCOPE>`: options `full` (Recommended), `api-only`,
-  `guides-only`, `targeted:<paths>`.
-- `<LIBRARY_ID>`: options enumerated from the filenames under
-  `skills/docs-sync/config/libraries/*.yml`. If only one slice exists,
-  skip the prompt and apply it as the default.
+## Step 1 — Confirm mode
 
-**Free-form inputs — ask via `AskUserQuestion` with a "Recommended"
-default option plus "Other" for custom input:**
+The mode arrives as input. This step normalizes it for the rest of the
+process:
 
-- `<CONTRACTS_REPO_PATH>`: an absolute filesystem path. No safe default
-  unless the user has previously supplied one this session.
-- `<BASE_COMMIT>` / `<HEAD_COMMIT>`: commit SHAs or refs in the
-  contracts repo. If reasonable, suggest the latest tag as `<BASE>` and
-  `HEAD` as `<HEAD>`; let the user override.
-- `<DOCS_VERSION>`: e.g. `1.x`. Suggest the highest existing version
-  directory in the slice.
-- `<RELEASE_VERSION>`: e.g. `v1.2.0`. No safe default; ask.
+- `interactive`: gates G1–G4 are active; broad rewrites need per-page
+  approval at G4.
+- `automatic`: gates are skipped; assumptions go into the final report.
 
-### 0.4 Validate as you collect
+## Step 2 — Load config memory
 
-After collection, validate inline and re-prompt on failure rather than
-deferring to later steps:
+1. Resolve `<CONFIG_PATH>`:
+   `skills/docs-sync/config/libraries/<library_id>.yml`.
+2. If the file does not exist, **stop** with a clear error. Do not
+   fabricate a config.
+3. Parse the file as YAML.
+4. Read `library.id`, `library.language`, `docs.*`, `navigation.*`,
+   `examples.*`, `security.*`, `release.*`, `automation.*`.
+5. Treat all `docs.*` paths as relative to `<DOCS_REPO_PATH>`.
+6. Apply optional overrides from runtime: `target_audience` overrides
+   `docs.target_audience`; `docs_tone` overrides `docs.tone`.
 
-- Paths exist and are git repos (`git -C <path> rev-parse
-  --is-inside-work-tree`).
-- `<CONTRACTS_REPO_PATH>` is not the same as `<DOCS_REPO_PATH>`.
-- `<BASE_COMMIT>` and `<HEAD_COMMIT>` resolve in the contracts repo
-  (`git -C <CONTRACTS_REPO_PATH> rev-parse --verify <SHA>^{commit}`).
-- `<LIBRARY_ID>` has a config file at
-  `skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`.
+---
 
-If a validation fails in interactive mode, re-prompt for just that
-field. If it fails in automatic mode (e.g. caller supplied a bad SHA),
-stop with a clear error.
+## 🛑 Gate G1 — Inputs & config confirmation
 
-Once all inputs are present and validated, proceed to Step 1. Steps 3
-and 4 below still run, but become no-ops because the same checks have
-already passed.
+Active in `interactive` mode only. After Step 2 completes successfully,
+emit the **G1 proposal block** (template:
+`references/proposals/g1-inputs-and-config.md`) and **end the turn**.
 
-## Step 1 — Select mode
+The proposal block MUST contain:
 
-1. If the caller passed `<MODE>`, use it.
-2. Otherwise read `automation.default_mode` from the config file
-   (Step 2).
-3. Otherwise default to `interactive`.
+- All resolved inputs, with each defaulted value clearly marked
+  `(default applied)`.
+- The resolved slice paths (`<LIBRARY_DOCS_ROOT>`, `<VERSION_DOCS_ROOT>`,
+  `<API_REFERENCE_PATH>`, `<NAV_CONFIG_PATH>`,
+  `<LOCAL_DOCS_CONVENTIONS_PATH>`).
+- Mode and scope, with one-line consequences for each.
+- Anything missing, ambiguous, or surprising flagged with `⚠️`.
+- A trailing line: `Reply "approve" to proceed, or describe corrections.`
 
-Mode behavior:
+When the user replies:
 
-- `interactive`: summarize and classify before broad edits. Ask only
-  questions whose answers change scope, examples, release notes,
-  audience, or security framing. API reference edits can proceed
-  deterministically; broad guide/tutorial/explanation rewrites need
-  confirmation.
-- `automatic`: ask no questions. Infer from config and sibling pages.
-  Record assumptions. If a required decision cannot be inferred safely,
-  stop or record `needs-human-review` rather than inventing context.
+- "approve" / "looks good" / "proceed" / "yes" → continue to Step 3.
+- Anything else → treat as refinement, apply the requested changes,
+  re-emit the G1 block, and wait again.
 
-## Step 2 — Load config memory
+In `automatic` mode, append the G1 contents to the final report's
+"Resolved inputs" section and continue to Step 3 without stopping.
 
-1. Resolve `<CONFIG_PATH>`. Default:
-   `skills/docs-sync/config/libraries/<LIBRARY_ID>.yml`.
-2. If the file does not exist, **stop**. Do not fabricate a config; ask
-   the user (interactive) or fail with a clear message (automatic).
-3. Parse the file as YAML.
-4. Read `library.id`, `library.language`, `docs.*`, `navigation.*`,
-   `examples.*`, `security.*`, `release.*`, `automation.*`.
-5. Treat all `docs.*` paths as relative to `<DOCS_REPO_PATH>`.
-6. Apply optional overrides from runtime: `<TARGET_AUDIENCE>` overrides
-   `docs.target_audience`; `<DOCS_TONE>` overrides `docs.tone`.
+---
 
 ## Step 3 — Resolve contracts repo and docs repo
 
-1. Verify `<CONTRACTS_REPO_PATH>` exists and is a git repository:
-   `git -C <CONTRACTS_REPO_PATH> rev-parse --is-inside-work-tree`.
-2. Verify `<DOCS_REPO_PATH>` exists and is a git repository.
-3. Confirm `<CONTRACTS_REPO_PATH>` is **not** the same as
-   `<DOCS_REPO_PATH>`.
-4. Confirm the docs repo's working tree is clean **enough** to make
+(Validation in Step 0.2 already covers most of this; redo the checks
+that depend on filesystem state at run time.)
+
+1. Confirm the docs repo's working tree is clean **enough** to make
    reviewable edits (no unrelated unstaged changes that would muddy the
    diff). Warn but continue if not.
 
-## Step 4 — Verify base and head commits
-
-```
-git -C <CONTRACTS_REPO_PATH> rev-parse --verify <BASE_COMMIT>^{commit}
-git -C <CONTRACTS_REPO_PATH> rev-parse --verify <HEAD_COMMIT>^{commit}
-```
-
-Both must resolve. If either fails:
-
-- Interactive: ask the user to fetch the right revision.
-- Automatic: stop with a clear error.
+## Step 4 — Verify base and head commits ancestry
 
-Confirm `<BASE_COMMIT>` is an ancestor of `<HEAD_COMMIT>`:
+Step 0.2 already verified both commits resolve. Now confirm
+`<BASE_COMMIT>` is an ancestor of `<HEAD_COMMIT>`:
 
 ```
 git -C <CONTRACTS_REPO_PATH> merge-base --is-ancestor <BASE_COMMIT> <HEAD_COMMIT>
@@ -165,7 +141,7 @@ git -C <CONTRACTS_REPO_PATH> diff --stat <BASE_COMMIT>..<HEAD_COMMIT>
 git -C <CONTRACTS_REPO_PATH> diff <BASE_COMMIT>..<HEAD_COMMIT>
 ```
 
-Persist the output for use in Steps 6–10. Also gather:
+Persist the output for use in Steps 6–11. Also gather:
 
 ```
 git -C <CONTRACTS_REPO_PATH> log --pretty=oneline <BASE_COMMIT>..<HEAD_COMMIT>
@@ -242,10 +218,10 @@ record the command. Produce a structured list:
 
 - Added modules / packages.
 - Removed modules / packages.
-- Added public functions, with signatures.
-- Removed public functions.
+- Added public functions, with full signatures.
+- Removed public functions, with full signatures.
 - Changed function signatures (parameter types/order, return type,
-  visibility, abilities).
+  visibility, abilities) — show **before → after** signatures.
 - Added or changed structs/types and their fields/abilities.
 - Added or removed constants.
 - Added or removed events.
@@ -256,6 +232,59 @@ The spec is language-agnostic; for `MOVE_SUI`, parse `module ...`
 declarations, `public fun`/`entry` signatures, `struct ... has ...`
 declarations, `const`s, error constants (`E*`), and event structs.
 
+This structured list is the input to Gate G2 below — make every entry
+self-explanatory (full signature, full module path) so the user can
+review without reopening source files.
+
+---
+
+## 🛑 Gate G2 — Public API delta confirmation
+
+Active in `interactive` mode only. After Step 9 completes, emit the
+**G2 proposal block** (template:
+`references/proposals/g2-api-delta.md`) and **end the turn**.
+
+The proposal block MUST contain, for each category, a bulleted list of
+items with full signatures:
+
+```
+### Added public functions
+- `module::path::function_name(arg: Type, ...): ReturnType`
+- ...
+
+### Removed public functions
+- `module::path::function_name(arg: Type, ...): ReturnType`
+- ...
+
+### Changed function signatures
+- `module::path::function_name`
+  - before: `(old_arg: OldType): OldReturn`
+  - after:  `(new_arg: NewType): NewReturn`
+- ...
+
+### Added / removed / changed structs, events, errors, constants
+- ...
+```
+
+Also include:
+
+- Total counts per category (`Added: 5 functions, 2 structs, …`).
+- A "Skipped (out of public surface)" list of contracts files Step 8
+  excluded, so the user can spot a wrongly-skipped file.
+- A trailing line: `Reply "approve" to proceed to docs planning, or
+  describe corrections (e.g. "treat foo as private", "include bar/").`
+
+When the user replies:
+
+- "approve" / "looks good" / "proceed" / "yes" → continue to Step 10.
+- Anything else → treat as refinement to the API surface (re-classify,
+  re-extract, etc.), re-emit the G2 block, and wait again.
+
+In `automatic` mode, append the G2 contents to the final report's
+"Public API delta" section and continue to Step 10 without stopping.
+
+---
+
 ## Step 10 — Classify changes
 
 Apply `references/rules/change-classification.md` to the structured
@@ -291,17 +320,80 @@ Apply `<DOCS_UPDATE_SCOPE>`:
   and API navigation updates only; report other required work as skipped.
 - `guides-only`: keep guide, tutorial, explanation, and snippet updates;
   do not regenerate API reference pages.
-- `targeted:<paths>`: keep only listed paths plus navigation changes
-  required for those paths; report omitted matrix-required work.
 
-In `interactive` mode, present the aggregated plan and wait for
-confirmation before broad rewrites of guides, tutorials, or
-explanations. API reference updates proceed without confirmation but
-follow `references/rules/api-reference-rules.md`.
+Build a per-file edit plan with:
+
+- `action`: one of `create`, `edit`, `delete`.
+- `path` relative to `<DOCS_REPO_PATH>`.
+- `category`: API reference / guide / tutorial / explanation / example /
+  navigation / release notes / security warning.
+- `covers`: which API items from Step 9 this file addresses (so the
+  user can sanity-check coverage).
+- `reason`: which matrix row(s) forced this entry.
+
+Also build a parallel "skipped" list for matrix-required updates that
+fall outside `<DOCS_UPDATE_SCOPE>` — every skipped item must be
+attributed to the scope choice that excluded it.
+
+---
+
+## 🛑 Gate G3 — Docs edit plan confirmation
+
+Active in `interactive` mode only. After Step 11 completes, emit the
+**G3 proposal block** (template:
+`references/proposals/g3-docs-edit-plan.md`) and **end the turn**.
+
+The proposal block MUST contain, in this order:
+
+```
+### Will create
+- <path> — <category> — covers: <api items> — reason: <matrix row>
+- ...
+
+### Will edit
+- <path> — <category> — covers: <api items> — reason: <matrix row>
+- ...
+
+### Will delete
+- <path> — <category> — reason: <matrix row>
+- ...
+
+### Will leave alone (matrix-required but out of <docs_update_scope>)
+- <path> — would have been <category> — excluded by scope=<value>
+- ...
+
+### Navigation deltas (will apply at Step 15)
+- add: <nav entry path>
+- remove: <nav entry path>
+- rename: <old> -> <new>
+```
+
+Also include:
+
+- Total counts (`5 to create, 12 to edit, 1 to delete, 3 skipped`).
+- A list of pages where the rewrite will be **broad** (full-section or
+  whole-page rewrite) vs **targeted** (single signature/snippet swap).
+  Broad rewrites trigger Gate G4 individually in Step 13.
+- A trailing line: `Reply "approve" to proceed with edits, or describe
+  scope changes (e.g. "skip release notes", "drop the new tutorial").`
+
+When the user replies:
+
+- "approve" / "looks good" / "proceed" / "yes" → continue to Step 12.
+- Anything else → treat as refinement, update the plan, re-emit the G3
+  block, and wait again.
+
+In `automatic` mode, append the G3 contents to the final report's
+"Docs edit plan" section and continue to Step 12 without stopping.
+
+---
 
 ## Step 12 — Update API reference
 
-Follow `references/rules/api-reference-rules.md`:
+API reference edits are deterministic translations of the API delta
+into reference pages — they proceed without per-page approval (the
+overall set was approved at G3). Follow
+`references/rules/api-reference-rules.md`:
 
 1. For each touched module, read the existing API reference page (if
    any) under `<API_REFERENCE_PATH>`.
@@ -320,13 +412,26 @@ Follow `references/rules/api-reference-rules.md`:
    to point to `<RELEASE_VERSION>` (or `<HEAD_COMMIT>` if no matching
    tag exists).
 
+After completing Step 12, output a one-line summary: `Step 12 — API
+reference updated: <N> files edited, <M> files created.` Then continue.
+
 ## Step 13 — Update guides, tutorials, and explanations
 
-For every guide/tutorial/explanation flagged in Step 11:
+For every guide/tutorial/explanation flagged in Step 11 and approved at
+G3, decide whether the rewrite is **targeted** (single
+signature/snippet/section change) or **broad** (multi-section or
+whole-page rewrite, new page, or Diátaxis category move).
+
+- **Targeted rewrites** proceed without further approval. Apply the
+  edit, then move on.
+- **Broad rewrites** stop at Gate G4 (below) and wait for per-page
+  approval before editing.
+
+For each rewrite (targeted or broad):
 
 1. Use `references/rules/diataxis-rules.md` to confirm the page is
    still in the right Diátaxis category. If not, propose a move
-   (interactive) or record it as a `needs-human-review` finding
+   (interactive, via G4) or record it as a `needs-human-review` finding
    (automatic).
 2. Apply the matching template (`references/templates/guide-template.md`,
    `references/templates/tutorial-template.md`,
@@ -340,6 +445,45 @@ For every guide/tutorial/explanation flagged in Step 11:
    `security.warning_style` and `security.require_security_sections_for`
    from config.
 
+---
+
+## 🛑 Gate G4 — Per-page rewrite confirmation (broad rewrites only)
+
+Active in `interactive` mode only, and only for **broad rewrites** as
+defined in Step 13. Targeted rewrites do not stop here.
+
+For each broad rewrite, before editing the file:
+
+1. Emit the **G4 proposal block** (template:
+   `references/proposals/g4-page-rewrite.md`).
+2. **End the turn** and wait for approval.
+
+The proposal block MUST contain:
+
+```
+### Page: <path>
+- Diátaxis category: <category> (unchanged | move from <old> to <new>)
+- Action: <create | rewrite | section-rewrite>
+- Sections affected: <list of section headings, or "whole page">
+- Triggered by: <api items from Step 9 + matrix row(s)>
+- Approach: <one paragraph describing the structure of the rewrite>
+
+Reply "approve" to apply this rewrite, or describe changes.
+```
+
+When the user replies:
+
+- "approve" → apply the rewrite and continue to the next broad rewrite
+  (or to Step 14 if none remain).
+- "skip" → record the page as `needs-human-review` and move on.
+- Anything else → treat as refinement, update the approach, re-emit the
+  G4 block for this page, and wait again.
+
+In `automatic` mode, all rewrites proceed without G4. Pages that would
+have triggered a Diátaxis move are recorded as `needs-human-review`.
+
+---
+
 ## Step 14 — Update examples
 
 If the docs slice has an `examples_root`, update it. If examples live as
@@ -353,7 +497,7 @@ fenced code blocks inside MDX, update those.
 
 ## Step 15 — Update navigation / sidebar
 
-Open `<NAV_CONFIG_PATH>` and apply the deltas:
+Open `<NAV_CONFIG_PATH>` and apply the deltas approved at G3:
 
 - Add new modules to the `Packages` and `API Reference` folders (or the
   equivalent labels for the slice).
diff --git a/skills/docs-sync/references/proposals/README.md b/skills/docs-sync/references/proposals/README.md
new file mode 100644
index 00000000..c0739c5e
--- /dev/null
+++ b/skills/docs-sync/references/proposals/README.md
@@ -0,0 +1,48 @@
+# Proposal templates for docs-sync gates
+
+In `interactive` mode, the docs-sync workflow stops at four gates. At
+each gate, the skill emits a structured **proposal block** based on one
+of the templates in this directory and ends its turn, waiting for the
+user to approve or refine.
+
+| Gate | Template                       | Stops after process step          |
+|------|--------------------------------|-----------------------------------|
+| G1   | `g1-inputs-and-config.md`      | Step 2 (config loaded)            |
+| G2   | `g2-api-delta.md`              | Step 9 (public API extracted)     |
+| G3   | `g3-docs-edit-plan.md`         | Step 11 (edit plan aggregated)    |
+| G4   | `g4-page-rewrite.md`           | per broad rewrite in Step 13      |
+
+## Approval phrases
+
+The skill MUST treat these (case-insensitive) as approval to proceed:
+
+- `approve`
+- `approved`
+- `looks good`
+- `lgtm`
+- `proceed`
+- `yes`
+- `go`
+
+Anything else is a **refinement** — apply the requested change, re-emit
+the same gate's proposal block with the updated content, and wait
+again. The skill MUST NOT proceed past a gate without explicit
+approval.
+
+## Style rules for proposal blocks
+
+- Plain markdown. No emoji except the `⚠️` flag on warning lines and the
+  `🛑` header marker on the gate heading itself.
+- Use full module paths and full function signatures — never truncate.
+- Counts go in the header (`12 to edit, 5 to create`) so the user can
+  triage before reading the full list.
+- One trailing line is always the approval prompt — no other content
+  after it.
+
+## Why no `AskUserQuestion`
+
+The skill body is atomic and Catalina-compliant. Inputs are gathered
+upfront via the frontmatter `inputs` schema. Mid-execution gates use
+plain text + end-of-turn instead of an interactive tool, which keeps
+the skill reusable in both Claude Code sessions and any harness that
+collects inputs without an interactive prompt loop.
diff --git a/skills/docs-sync/references/proposals/g1-inputs-and-config.md b/skills/docs-sync/references/proposals/g1-inputs-and-config.md
new file mode 100644
index 00000000..f5e03298
--- /dev/null
+++ b/skills/docs-sync/references/proposals/g1-inputs-and-config.md
@@ -0,0 +1,39 @@
+# G1 proposal template — Inputs & config
+
+Emit this block at the end of process Step 2 in `interactive` mode.
+End the turn after the trailing approval line. Do not interleave any
+other tool calls or text after the block.
+
+```
+🛑 Gate G1 — Inputs & config
+
+### Resolved inputs
+- mode:                <value>           [default applied | from caller]
+- contracts_repo_path: <abs path>
+- docs_repo_path:      <abs path>        [default applied: cwd]
+- base_commit:         <sha or ref>      (resolves to <full sha>)
+- head_commit:         <sha or ref>      (resolves to <full sha>)
+- library_id:          <id>
+- docs_version:        <version>
+- release_version:     <release tag>
+- docs_update_scope:   <value>           [default applied: full]
+- target_audience:     <value>           [from config | overridden]
+- docs_tone:           <value>           [from config | overridden]
+
+### Resolved slice paths (relative to docs_repo_path)
+- library root:        <docs.library_root>
+- version root:        <docs.version_root>
+- API reference:       <docs.api_reference_path>
+- nav config:          <docs.nav_config_path>
+- local conventions:   <docs.local_conventions_path>
+
+### Mode and scope
+- mode = <interactive|automatic> — <one-line consequence>
+- scope = <full|api-only|guides-only> — <one-line consequence>
+
+### Flags
+- ⚠️ <anything missing, ambiguous, or surprising — one line each>
+- (omit this section entirely if there are no flags)
+
+Reply "approve" to proceed, or describe corrections.
+```
diff --git a/skills/docs-sync/references/proposals/g2-api-delta.md b/skills/docs-sync/references/proposals/g2-api-delta.md
new file mode 100644
index 00000000..49fd1b2d
--- /dev/null
+++ b/skills/docs-sync/references/proposals/g2-api-delta.md
@@ -0,0 +1,81 @@
+# G2 proposal template — Public API delta
+
+Emit this block at the end of process Step 9 in `interactive` mode.
+End the turn after the trailing approval line. Use full module paths
+and full signatures — never truncate.
+
+If a category is empty, write `(none)` rather than omitting the
+heading; reviewers should be able to confirm at a glance that the
+category was actually checked.
+
+```
+🛑 Gate G2 — Public API delta
+Summary: +<N> functions, +<N> structs, +<N> events, +<N> errors,
+         -<N> functions, -<N> structs, -<N> events, -<N> errors,
+         <N> changed signatures, <N> changed doc comments
+Diff range: <BASE_COMMIT>..<HEAD_COMMIT> (<N> commits)
+
+### Added modules / packages
+- <module::path>
+- (none)
+
+### Removed modules / packages
+- <module::path>
+- (none)
+
+### Added public functions
+- `<module::path::function_name(arg: Type, ...): ReturnType>`
+- (none)
+
+### Removed public functions
+- `<module::path::function_name(arg: Type, ...): ReturnType>`
+- (none)
+
+### Changed function signatures
+- `<module::path::function_name>`
+  - before: `(<old args>): <old return>`
+  - after:  `(<new args>): <new return>`
+- (none)
+
+### Added structs / types
+- `<module::path::StructName has copy, drop>`
+  - fields: <field: Type, ...>
+- (none)
+
+### Changed structs / types
+- `<module::path::StructName>`
+  - field changes: <field: Type added | removed | changed Type>
+  - ability changes: <added/removed abilities>
+- (none)
+
+### Removed structs / types
+- `<module::path::StructName>`
+- (none)
+
+### Added / removed constants
+- added:   `<module::path::CONST_NAME: Type = value>`
+- removed: `<module::path::CONST_NAME>`
+- (none)
+
+### Added / removed events
+- added:   `<module::path::EventName>`
+- removed: `<module::path::EventName>`
+- (none)
+
+### Added / removed errors / abort codes
+- added:   `<module::path::EErrorName = N>`
+- removed: `<module::path::EErrorName>`
+- (none)
+
+### Changed doc comments on public items
+- `<module::path::item>` — <one-line summary of the comment change>
+- (none)
+
+### Skipped (out of public surface)
+- <contracts file path> — reason: <tests/ | scripts/ | internal/ | vendored/>
+- (none — say so explicitly so the reviewer knows nothing was hidden)
+
+Reply "approve" to proceed to docs planning, or describe corrections
+(e.g. "treat foo as private", "include bar/", "the change to baz is
+internal only").
+```
diff --git a/skills/docs-sync/references/proposals/g3-docs-edit-plan.md b/skills/docs-sync/references/proposals/g3-docs-edit-plan.md
new file mode 100644
index 00000000..4c55029a
--- /dev/null
+++ b/skills/docs-sync/references/proposals/g3-docs-edit-plan.md
@@ -0,0 +1,52 @@
+# G3 proposal template — Docs edit plan
+
+Emit this block at the end of process Step 11 in `interactive` mode.
+End the turn after the trailing approval line. Every entry MUST attribute
+the action to (a) the API items it covers and (b) the matrix row that
+forced it — this lets the reviewer challenge specific lines without
+re-deriving the plan.
+
+If a section is empty, write `(none)` rather than omitting the heading.
+
+```
+🛑 Gate G3 — Docs edit plan
+Summary: <N> to create, <N> to edit, <N> to delete, <N> skipped (out of scope)
+Scope: <full | api-only | guides-only>
+
+### Will create
+- <path> — <category> — covers: <api items> — reason: <matrix row>
+- (none)
+
+### Will edit
+- <path> — <category> — covers: <api items> — reason: <matrix row>
+- (none)
+
+### Will delete
+- <path> — <category> — reason: <matrix row>
+- (none)
+
+### Will leave alone (matrix-required but out of <docs_update_scope>)
+- <path> — would have been <category> — excluded by scope=<value>
+- (none)
+
+### Navigation deltas (will apply at Step 15)
+- add:    <nav entry path>
+- remove: <nav entry path>
+- rename: <old path> -> <new path>
+- (none)
+
+### Rewrite breadth (drives Gate G4 in Step 13)
+- broad rewrites (will stop at G4 individually):
+  - <path> — <reason for broad classification>
+  - (none)
+- targeted rewrites (will apply without further approval):
+  - <path> — <one-line summary of the change>
+  - (none)
+
+### Assumptions
+- <one line per assumption — defaults applied, fallbacks taken, etc.>
+- (none)
+
+Reply "approve" to proceed with edits, or describe scope changes (e.g.
+"skip release notes", "drop the new tutorial", "also include path X").
+```
diff --git a/skills/docs-sync/references/proposals/g4-page-rewrite.md b/skills/docs-sync/references/proposals/g4-page-rewrite.md
new file mode 100644
index 00000000..5a289541
--- /dev/null
+++ b/skills/docs-sync/references/proposals/g4-page-rewrite.md
@@ -0,0 +1,41 @@
+# G4 proposal template — Per-page broad rewrite
+
+Emit this block in process Step 13, in `interactive` mode, **once per
+broad rewrite** before editing the file. Targeted rewrites do not stop
+at G4. End the turn after the trailing approval line.
+
+```
+🛑 Gate G4 — Page rewrite: <path>
+
+- Diátaxis category: <tutorial | how-to | reference | explanation>
+  - move: <unchanged> | <old category> -> <new category>
+- Action: <create | rewrite-whole-page | rewrite-sections>
+- Sections affected: <list of section headings, or "whole page">
+- Triggered by:
+  - api items: <list from Step 9 — full names>
+  - matrix row: <row id or one-line description>
+- Approach: <one paragraph describing the structure and substance of
+  the rewrite — what stays, what changes, what gets added>
+- Risk / `needs-human-review` flags:
+  - <one line per concern, or "none">
+
+Reply "approve" to apply this rewrite, "skip" to leave the page as-is
+and record needs-human-review, or describe changes to the approach.
+```
+
+## When to classify a rewrite as "broad" (and thus subject to G4)
+
+Per process Step 13, a rewrite is **broad** when any of the following
+is true:
+
+- The page is being created from scratch.
+- The Diátaxis category is moving.
+- More than one named section is being rewritten.
+- The whole page is being regenerated.
+- The change adds or removes a security warning section.
+
+Otherwise, the rewrite is **targeted** — single signature swap, single
+snippet update, one short paragraph edit — and proceeds without G4.
+
+When in doubt, classify as broad. The cost of an extra G4 stop is small;
+the cost of a silent broad rewrite is large.
diff --git a/src/navigation/sui/current.json b/src/navigation/sui/current.json
index fb1885d9..2f363c23 100644
--- a/src/navigation/sui/current.json
+++ b/src/navigation/sui/current.json
@@ -13,28 +13,6 @@
 		"name": "Overview",
 		"url": "/contracts-sui/1.x"
 	},
-	{
-		"type": "folder",
-		"name": "Learn",
-		"defaultOpen": false,
-		"children": [
-			{
-				"type": "page",
-				"name": "Overview",
-				"url": "/contracts-sui/1.x/learn"
-			},
-			{
-				"type": "page",
-				"name": "Math Walkthrough",
-				"url": "/contracts-sui/1.x/learn/math-walkthrough"
-			},
-			{
-				"type": "page",
-				"name": "Access Walkthrough",
-				"url": "/contracts-sui/1.x/learn/access-walkthrough"
-			}
-		]
-	},
 	{
 		"type": "folder",
 		"name": "Packages",

From 87d21acf3f332cd0fcb75ebe981cc2ab20613116 Mon Sep 17 00:00:00 2001
From: Eric Nordelo <eric.nordelo39@gmail.com>
Date: Mon, 4 May 2026 16:19:17 +0200
Subject: [PATCH 4/5] feat: update skill

---
 content/contracts-sui/1.x/access.mdx                    | 7 -------
 content/contracts-sui/1.x/fixed-point.mdx               | 3 ---
 content/contracts-sui/1.x/math.mdx                      | 3 ---
 skills/docs-sync/references/rules/diataxis-rules.md     | 3 +++
 skills/docs-sync/references/rules/docs-pr-checklist.md  | 1 +
 skills/docs-sync/references/templates/guide-template.md | 4 ++--
 6 files changed, 6 insertions(+), 15 deletions(-)

diff --git a/content/contracts-sui/1.x/access.mdx b/content/contracts-sui/1.x/access.mdx
index ffaa78ae..7d3d35f5 100644
--- a/content/contracts-sui/1.x/access.mdx
+++ b/content/contracts-sui/1.x/access.mdx
@@ -14,8 +14,6 @@ Use this package when direct object transfer is too permissive for your protocol
 This package is designed for single-owned objects. In `two_step_transfer`, `ctx.sender()` is stored as the owner-of-record for pending requests. Avoid using this policy directly in shared-object executor flows unless your design explicitly maps signer identity to cancel authority.
 </Callout>
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access)
-
 ## Usage
 
 Add the dependency in `Move.toml`:
@@ -123,8 +121,6 @@ If you try to drop the borrow token, return a different capability, or return it
 
 ## `two_step_transfer`
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/two_step.move)
-
 A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay, thus the transfer executes immediately once the recipient accepts.
 
 This is the right choice when the principal initiating the transfer is a known, controlled key (a multisig, a hot wallet operated by the same team) and the risk you are guarding against is sending the capability to a wrong or non-existent address, which would permanently lock the capability with no way to recover it.
@@ -206,8 +202,6 @@ Avoid using `two_step_transfer` in shared-object executor flows unless your desi
 
 ## `delayed_transfer`
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/blob/v1.1.0/contracts/access/sources/ownership_transfer/delayed.move)
-
 A transfer policy that enforces a configurable minimum delay between scheduling and executing a transfer. The delay is set at wrap time and cannot be changed afterward. This creates a publicly visible window before any authority change takes effect, giving monitoring systems, DAOs, and individual users time to detect and respond.
 
 This is the right choice when your protocol requires on-chain lead time before a capability changes hands, for example, to allow an incident response process to detect a compromised key, or to give depositors time to exit before governance parameters change.
@@ -358,6 +352,5 @@ For function-level signatures and parameters, see the [Access API reference](/co
 - [Access API reference](/contracts-sui/1.x/api/access) for full function signatures and error codes
 - [Integer Math](/contracts-sui/1.x/math) for safe arithmetic primitives used in protocol math
 - [Fixed-Point Math](/contracts-sui/1.x/fixed-point) for fractional values, prices, and signed deltas
-- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/contracts/access) for inline documentation and implementation details
 - [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
 - [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/fixed-point.mdx b/content/contracts-sui/1.x/fixed-point.mdx
index 8581edbd..26a4a05f 100644
--- a/content/contracts-sui/1.x/fixed-point.mdx
+++ b/content/contracts-sui/1.x/fixed-point.mdx
@@ -10,8 +10,6 @@ The `openzeppelin_fp_math` package adds two decimal fixed-point types with 9 dec
 
 The package complements `openzeppelin_math`, which covers integer arithmetic. Use `openzeppelin_math` when your values are whole numbers; reach for `openzeppelin_fp_math` when fractional values are part of the protocol.
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/fixed_point)
-
 ## Why a 9-decimal scale
 
 - Matches Sui's native coin decimals, so converting between token amounts and fixed-point values is straightforward.
@@ -483,6 +481,5 @@ For function-level signatures and parameters, see the [Fixed-Point Math API refe
 - [Fixed-Point Math API reference](/contracts-sui/1.x/api/fixed-point) for full function signatures
 - [Integer Math](/contracts-sui/1.x/math) for integer arithmetic primitives
 - [Access](/contracts-sui/1.x/access) for ownership-transfer policies on privileged capabilities
-- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/fixed_point) for inline documentation and implementation details
 - [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
 - [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/content/contracts-sui/1.x/math.mdx b/content/contracts-sui/1.x/math.mdx
index cf97d073..e2c7e88a 100644
--- a/content/contracts-sui/1.x/math.mdx
+++ b/content/contracts-sui/1.x/math.mdx
@@ -10,8 +10,6 @@ The `openzeppelin_math` package is the numeric foundation for OpenZeppelin Contr
 
 Use this package when your app needs arithmetic behavior that is predictable, auditable, and safe around overflow and precision boundaries. Instead of hiding rounding and truncation inside implementation details, `openzeppelin_math` makes those decisions explicit so they can be part of your protocol rules.
 
-[Source Code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core)
-
 ## Usage
 
 Add the dependency in `Move.toml`:
@@ -393,6 +391,5 @@ For function-level signatures and parameters, see the [Integer Math API referenc
 - [Integer Math API reference](/contracts-sui/1.x/api/math) for full function signatures
 - [Fixed-Point Math](/contracts-sui/1.x/fixed-point) for fractional values, prices, and signed deltas
 - [Access](/contracts-sui/1.x/access) for ownership-transfer policies on privileged capabilities
-- [Source code](https://github.com/OpenZeppelin/contracts-sui/tree/main/math/core) for inline documentation and implementation details
 - [GitHub issue tracker](https://github.com/OpenZeppelin/contracts-sui/issues) to report bugs or request features
 - [Sui Discord](https://discord.gg/sui) and [Sui Developer Forum](https://forums.sui.io/) to connect with other builders
diff --git a/skills/docs-sync/references/rules/diataxis-rules.md b/skills/docs-sync/references/rules/diataxis-rules.md
index f808693a..07769eaa 100644
--- a/skills/docs-sync/references/rules/diataxis-rules.md
+++ b/skills/docs-sync/references/rules/diataxis-rules.md
@@ -67,6 +67,9 @@ security model, and design context.
    first sentence to make the category obvious.
 6. **One outcome per guide. One topic per explanation. One artifact per
    tutorial.** When two outcomes belong together, split the page.
+7. **Source links belong in Reference.** Tutorials, guides, and
+   explanations should link to the related API reference, not directly
+   to source code. API reference owns source links.
 
 ---
 
diff --git a/skills/docs-sync/references/rules/docs-pr-checklist.md b/skills/docs-sync/references/rules/docs-pr-checklist.md
index 77fbdd05..58521a58 100644
--- a/skills/docs-sync/references/rules/docs-pr-checklist.md
+++ b/skills/docs-sync/references/rules/docs-pr-checklist.md
@@ -61,6 +61,7 @@ within configured rules) or surface it explicitly.
 
 - [ ] Internal links inside the slice resolve to existing pages.
 - [ ] Anchors inside the slice resolve to existing ids.
+- [ ] Source-code links appear only in API reference pages.
 - [ ] No `#TODO`, `<TODO>`, or template `<PLACEHOLDER>` tokens remain
   unless `automation.fail_on_unresolved_placeholders: false`.
 
diff --git a/skills/docs-sync/references/templates/guide-template.md b/skills/docs-sync/references/templates/guide-template.md
index aafb25a8..9d2f2c57 100644
--- a/skills/docs-sync/references/templates/guide-template.md
+++ b/skills/docs-sync/references/templates/guide-template.md
@@ -17,8 +17,6 @@ title: <Action verb + object> (e.g. "Rotate an admin capability")
 description: <One sentence describing the user goal.>
 ---
 
-import { APIItem, APIGithubLinkHeader } from "@/components/api"
-
 # <Title>
 
 ## Goal
@@ -143,5 +141,7 @@ module my_app::full_example;
   valid, write two guides.
 - Do not include narrative context that does not advance the task. The
   reader is busy.
+- Do not include source-code links in guides. Link to the related API
+  reference instead; API reference pages own source links.
 - Match `docs.tone` from config. Default for the contracts-sui slice:
   *clear, precise, security-conscious*.

From 21a9181016bc48d0917d04f83b6d8ddf173077ad Mon Sep 17 00:00:00 2001
From: stevep0z <255929980+stevep0z@users.noreply.github.com>
Date: Mon, 11 May 2026 14:42:09 -0500
Subject: [PATCH 5/5] docs: polish prose in contracts-sui v1.1.0 guides

---
 content/contracts-sui/1.x/access.mdx      |  4 +-
 content/contracts-sui/1.x/api/math.mdx    |  2 +-
 content/contracts-sui/1.x/fixed-point.mdx | 70 +++++++++++------------
 content/contracts-sui/1.x/index.mdx       |  4 +-
 content/contracts-sui/1.x/math.mdx        |  6 +-
 5 files changed, 43 insertions(+), 43 deletions(-)

diff --git a/content/contracts-sui/1.x/access.mdx b/content/contracts-sui/1.x/access.mdx
index 7d3d35f5..13542e74 100644
--- a/content/contracts-sui/1.x/access.mdx
+++ b/content/contracts-sui/1.x/access.mdx
@@ -3,7 +3,7 @@ title: Access
 ---
 
 <Callout type="warn">
-The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+The example code snippets used in this guide are experimental and have not been audited. They are meant to illustrate usage of the OpenZeppelin Sui Package.
 </Callout>
 
 The `openzeppelin_access` package provides ownership-transfer wrappers for privileged Sui objects (`T: key + store`), such as admin and treasury capabilities.
@@ -121,7 +121,7 @@ If you try to drop the borrow token, return a different capability, or return it
 
 ## `two_step_transfer`
 
-A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay, thus the transfer executes immediately once the recipient accepts.
+A transfer policy that requires the designated recipient to explicitly accept before the wrapper changes hands. The initiator retains cancel authority until acceptance. There is no time delay. The transfer executes immediately once the recipient accepts.
 
 This is the right choice when the principal initiating the transfer is a known, controlled key (a multisig, a hot wallet operated by the same team) and the risk you are guarding against is sending the capability to a wrong or non-existent address, which would permanently lock the capability with no way to recover it.
 
diff --git a/content/contracts-sui/1.x/api/math.mdx b/content/contracts-sui/1.x/api/math.mdx
index ebcd923c..43611dd9 100644
--- a/content/contracts-sui/1.x/api/math.mdx
+++ b/content/contracts-sui/1.x/api/math.mdx
@@ -465,7 +465,7 @@ NOTE: Unstable sort. Average time complexity is `O(n log n)`; theoretical worst
   id="vector-quick_sort_by"
   kind="public"
 >
-Sorts a vector in place using a caller-supplied comparison function. The comparator must implement **non-strict** ordering (`<=` for ascending, `>=` for descending) — using a strict comparator (`<` or `>`) defeats three-way partitioning and degrades performance to `O(n^2)` when duplicates are present.
+Sorts a vector in place using a caller-supplied comparison function. The comparator must implement **non-strict** ordering (`<=` for ascending, `>=` for descending). Using a strict comparator (`<` or `>`) defeats three-way partitioning and degrades performance to `O(n^2)` when duplicates are present.
 
 NOTE: Unstable sort. The same complexity caveats as [`quick_sort`](#vector-quick_sort) apply.
 </APIItem>
diff --git a/content/contracts-sui/1.x/fixed-point.mdx b/content/contracts-sui/1.x/fixed-point.mdx
index 26a4a05f..6316cbdc 100644
--- a/content/contracts-sui/1.x/fixed-point.mdx
+++ b/content/contracts-sui/1.x/fixed-point.mdx
@@ -3,23 +3,23 @@ title: Fixed-Point Math
 ---
 
 <Callout type="warn">
-The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+The example code snippets used in this guide are experimental and have not been audited. They are meant to illustrate usage of the OpenZeppelin Sui Package.
 </Callout>
 
-The `openzeppelin_fp_math` package adds two decimal fixed-point types with 9 decimals of precision, matching Sui's native coin precision (`10^9`). It is the right tool whenever you need real-valued arithmetic — prices, fees, rates, ratios, balance deltas — without giving up determinism or onchain auditability.
+The `openzeppelin_fp_math` package adds two decimal fixed-point types with 9 decimals of precision, matching Sui's native coin precision (`10^9`). It is the right tool whenever you need real-valued arithmetic such as prices, fees, rates, ratios, and balance deltas, without giving up determinism or onchain auditability.
 
 The package complements `openzeppelin_math`, which covers integer arithmetic. Use `openzeppelin_math` when your values are whole numbers; reach for `openzeppelin_fp_math` when fractional values are part of the protocol.
 
 ## Why a 9-decimal scale
 
 - Matches Sui's native coin decimals, so converting between token amounts and fixed-point values is straightforward.
-- Decimal scale is intuitive for humans, UIs, and offchain systems — `1.5` is `1_500_000_000`, no binary fixed-point surprises.
+- Decimal scale is intuitive for humans, UIs, and offchain systems. `1.5` is `1_500_000_000`, with no binary fixed-point surprises.
 - Fits in `u128`, keeping storage and arithmetic light compared to `u256`-based decimal types.
 
 ## The two types
 
-- [`UD30x9`](/contracts-sui/1.x/api/fixed-point#ud30x9) — unsigned. Decimal range from `0` to roughly `3.4 × 10^29`.
-- [`SD29x9`](/contracts-sui/1.x/api/fixed-point#sd29x9) — signed (two's complement). Decimal range from roughly `-1.7 × 10^29` to `1.7 × 10^29`. Useful for balance deltas, signed adjustments, and any quantity that can dip below zero.
+- [`UD30x9`](/contracts-sui/1.x/api/fixed-point#ud30x9): unsigned. Decimal range from `0` to roughly `3.4 × 10^29`.
+- [`SD29x9`](/contracts-sui/1.x/api/fixed-point#sd29x9): signed (two's complement). Decimal range from roughly `-1.7 × 10^29` to `1.7 × 10^29`. Useful for balance deltas, signed adjustments, and any quantity that can dip below zero.
 
 The names encode the layout: `UD30x9` uses up to 30 integer digits with 9 fractional digits, `SD29x9` is the signed counterpart with one bit reserved for the sign. Both fit in 16 bytes of storage, so swapping `u128` for either type costs nothing in storage or arithmetic budget.
 
@@ -100,11 +100,11 @@ public fun settle(amount: ud30x9::UD30x9): u64 {
 
 ## Choosing a function
 
-- `mul`, `div` — round toward zero. Equivalent to `mul_trunc`, `div_trunc`. Use as the default when rounding direction does not matter.
-- `mul_trunc`, `div_trunc` — round toward zero (truncate). Use when you want to spell the rounding direction out at the call site.
-- `mul_away`, `div_away` — round away from zero when inexact. Use for fees, slippage caps, and protocol-side accounting where rounding should never favor the user against the protocol.
-- `unchecked_add`, `unchecked_sub` — wrap modulo `2^128` instead of aborting on overflow/underflow. Use only when you have already proved the operation is safe and you want to avoid the abort path; otherwise prefer `add` / `sub`.
-- `pow` — approximate, biased toward zero, and not associative under truncation. Reasonable for small, integer exponents over typical fixed-point ranges; verify expected behavior at your application's exponent and operand magnitudes before relying on it.
+- `mul`, `div`: round toward zero. Equivalent to `mul_trunc`, `div_trunc`. Use as the default when rounding direction does not matter.
+- `mul_trunc`, `div_trunc`: round toward zero (truncate). Use when you want to spell the rounding direction out at the call site.
+- `mul_away`, `div_away`: round away from zero when inexact. Use for fees, slippage caps, and protocol-side accounting where rounding should never favor the user against the protocol.
+- `unchecked_add`, `unchecked_sub`: wrap modulo `2^128` instead of aborting on overflow/underflow. Use only when you have already proved the operation is safe and you want to avoid the abort path. Otherwise prefer `add` / `sub`.
+- `pow`: approximate, biased toward zero, and not associative under truncation. Reasonable for small, integer exponents over typical fixed-point ranges. Verify expected behavior at your application's exponent and operand magnitudes before relying on it.
 
 For `SD29x9` specifically, prefer `mod` (Euclidean, always non-negative) over `rem` (truncating, sign follows dividend) unless your protocol explicitly wants the truncating variant.
 
@@ -116,12 +116,12 @@ For `SD29x9` specifically, prefer `mod` (Euclidean, always non-negative) over `r
 
 ## Why fixed-point on-chain
 
-Move has no native fractional type. Real-valued protocol math — prices, fees, interest rates, signed balance deltas — has to be encoded in integers. The naive approach is to scale by a power of two ("Q-notation": Q64.64, Q96, Q128, etc.) and use bit shifts. That works, but it has two persistent drawbacks:
+Move has no native fractional type. Real-valued protocol math (prices, fees, interest rates, signed balance deltas) has to be encoded in integers. The naive approach is to scale by a power of two ("Q-notation": Q64.64, Q96, Q128, etc.) and use bit shifts. That works, but it has two persistent drawbacks:
 
 1. **Binary scales misalign with the units protocols actually report.** Token amounts, exchange rates, and oracle prices are quoted as decimals. Converting to and from a binary scale at every boundary creates rounding seams that are easy to get wrong and hard to audit.
 2. **Bit-shift arithmetic puts the rounding decision in the operator instead of the call site.** A `>>` is silent. A `mul_div`-shaped helper makes the rounding direction visible. The Cetus exploit hinged on a `checked_shl`-shaped function that silently passed a value it should have rejected; the same class of bug is harder to write when rounding is a named choice at every call site.
 
-`openzeppelin_fp_math` picks **decimal** fixed-point with **9 decimals** (`10^9`) — the same precision Sui uses for native coin amounts. `1.5` is `1_500_000_000`, `0.000_000_001` is `1`. Conversions between token amounts and fixed-point values become a single multiply or divide by `10^9`, with no bit-pattern reasoning involved.
+`openzeppelin_fp_math` picks **decimal** fixed-point with **9 decimals** (`10^9`), matching the precision Sui uses for native coin amounts. `1.5` is `1_500_000_000`, `0.000_000_001` is `1`. Conversions between token amounts and fixed-point values become a single multiply or divide by `10^9`, with no bit-pattern reasoning involved.
 
 The package complements `openzeppelin_math`: integer arithmetic stays in `openzeppelin_math`, fractional arithmetic lives here. They use the same explicit-rounding philosophy.
 
@@ -129,7 +129,7 @@ The package complements `openzeppelin_math`: integer arithmetic stays in `openze
 
 The package draws a sharp line between two kinds of "convert this number to fixed-point" operations. Mixing them up is the most common way to introduce a `10^9`-sized bug, so it is worth getting clear on before writing any arithmetic.
 
-### Casting — preserves raw scaled bits
+### Casting (preserves raw scaled bits)
 
 Casting reinterprets a value that is **already in fixed-point form**. It does not multiply or divide by `10^9`.
 
@@ -139,7 +139,7 @@ The core cast helpers live on the `sd29x9` and `ud30x9` modules:
 use openzeppelin_fp_math::{sd29x9, ud30x9};
 
 let one = ud30x9::wrap(1_000_000_000); // 1.0
-let raw = ud30x9::wrap(42);            // 0.000000042 — NOT 42.0
+let raw = ud30x9::wrap(42);            // 0.000000042, NOT 42.0
 
 let positive_one = sd29x9::wrap(1_000_000_000, false); // 1.0
 let small_negative = sd29x9::wrap(42, true);           // -0.000000042
@@ -157,15 +157,15 @@ let roundtrip = signed.into_UD30x9();         // 42.0 as UD30x9
 
 Use casting when your input is already fixed-point bits (e.g., loaded from storage, returned by another fixed-point function, or hand-encoded in a constant).
 
-### Converting — applies or removes the `10^9` scale
+### Converting (applies or removes the `10^9` scale)
 
 Converting changes between **whole-integer** semantics and **fixed-point** semantics. Use the `*_convert` modules for this.
 
 ```move
 use openzeppelin_fp_math::{sd29x9_convert, ud30x9_convert};
 
-let whole = ud30x9_convert::from_u128(42); // 42.0 — multiplies by 10^9
-let back = whole.to_u128_trunc();          // 42  — divides by 10^9, truncates fractional
+let whole = ud30x9_convert::from_u128(42); // 42.0, multiplies by 10^9
+let back = whole.to_u128_trunc();          // 42, divides by 10^9, truncates fractional
 
 let delta = sd29x9_convert::from_u128(5, true); // -5.0
 let (magnitude, is_negative) = delta.to_parts_trunc();
@@ -207,7 +207,7 @@ Like `openzeppelin_math`, this package treats rounding as a protocol decision. B
 
 | Function pair | Rounding | When to use |
 |---|---|---|
-| `mul`, `mul_trunc` | toward zero | Default. The two are aliases — pick `mul_trunc` if you want the rounding direction visible at the call site. |
+| `mul`, `mul_trunc` | toward zero | Default. The two are aliases. Pick `mul_trunc` if you want the rounding direction visible at the call site. |
 | `mul_away` | away from zero | Fees, slippage caps, anywhere the protocol should never undercharge or under-reserve. |
 | `div`, `div_trunc` | toward zero | Default for division. Same alias relationship as `mul`. |
 | `div_away` | away from zero | When the divisor is user-supplied or quote-related and the protocol must bound itself conservatively. |
@@ -217,12 +217,12 @@ The same vault-lifecycle logic from the integer-math guide applies here, just wi
 ```move
 use openzeppelin_fp_math::ud30x9::UD30x9;
 
-/// Convert tokens to shares — round toward zero so the vault keeps the dust.
+/// Convert tokens to shares, rounding toward zero so the vault keeps the dust.
 public fun deposit_shares(amount: UD30x9, total_assets: UD30x9, total_supply: UD30x9): UD30x9 {
     amount.mul_trunc(total_supply).div_trunc(total_assets)
 }
 
-/// Convert shares to tokens — round toward zero so the vault keeps the dust.
+/// Convert shares to tokens, rounding toward zero so the vault keeps the dust.
 public fun withdraw_assets(shares: UD30x9, total_assets: UD30x9, total_supply: UD30x9): UD30x9 {
     shares.mul_trunc(total_assets).div_trunc(total_supply)
 }
@@ -232,7 +232,7 @@ Both directions truncate toward zero, so the vault never gives away fractional r
 
 ### When `_trunc` and `_away` differ
 
-`mul` and `mul_trunc` differ only when the exact mathematical product cannot be represented in 9 decimals. For values that already fit cleanly, `mul_trunc(x, y) == mul_away(x, y)`. The choice only matters at the precision boundary — which, in fee-and-rate land, is exactly where it matters most.
+`mul` and `mul_trunc` differ only when the exact mathematical product cannot be represented in 9 decimals. For values that already fit cleanly, `mul_trunc(x, y) == mul_away(x, y)`. The choice only matters at the precision boundary, which in fee-and-rate land is exactly where it matters most.
 
 `div_away` is the helper you want for inverse-rate conversions. `1.0 / 3.0` is `0.333333333` with `div_trunc` and `0.333333334` with `div_away`. If your protocol owes the user some fraction of `x / 3`, rounding down on each individual settlement systematically under-pays the user.
 
@@ -240,9 +240,9 @@ Both directions truncate toward zero, so the vault never gives away fractional r
 
 Unlike `openzeppelin_math`, the fixed-point package does **not** return `Option<T>` from arithmetic. It aborts. The error constants come in three families:
 
-- **`EOverflow`** — the result exceeds the representable range of the target type.
-- **`EUnderflow`** — applies to `UD30x9::sub` only. Subtraction would produce a negative value, which is unrepresentable in an unsigned type.
-- **`EDivideByZero`** — applies to `div`, `div_trunc`, `div_away`, `mod`, and `rem`.
+- **`EOverflow`**: the result exceeds the representable range of the target type.
+- **`EUnderflow`**: applies to `UD30x9::sub` only. Subtraction would produce a negative value, which is unrepresentable in an unsigned type.
+- **`EDivideByZero`**: applies to `div`, `div_trunc`, `div_away`, `mod`, and `rem`.
 
 There are also the unchecked-add and unchecked-subtract escape hatches, plus `unchecked_lshift` / `unchecked_rshift` on `UD30x9`. They wrap modulo `2^128` instead of aborting.
 
@@ -275,7 +275,7 @@ public fun try_add(x: UD30x9, y: UD30x9): Option<UD30x9> {
 
 ## Comparison and equality
 
-Comparison operators on `UD30x9` and `SD29x9` work how you would expect — `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `is_zero` — with one subtle point on the signed type:
+Comparison operators on `UD30x9` and `SD29x9` work as you would expect (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `is_zero`). There is one subtle point on the signed type:
 
 ```move
 use openzeppelin_fp_math::sd29x9;
@@ -286,7 +286,7 @@ let b = sd29x9::wrap(0, true);
 let same = a.eq(b); // true
 ```
 
-`SD29x9::wrap` rejects "negative zero" by mapping `(0, true)` and `(0, false)` to the same underlying bits, so equality on zeros behaves as expected. If you ever construct an `SD29x9` from raw bits via the package-internal `from_bits`, this normalization does not happen — but `from_bits` is not part of the public API surface, so most callers never encounter it.
+`SD29x9::wrap` rejects "negative zero" by mapping `(0, true)` and `(0, false)` to the same underlying bits, so equality on zeros behaves as expected. If you ever construct an `SD29x9` from raw bits via the package-internal `from_bits`, this normalization does not happen, but `from_bits` is not part of the public API surface, so most callers never encounter it.
 
 ## Cross-type casts
 
@@ -310,7 +310,7 @@ Each direction has a `try_into_*` counterpart that returns `Option<T>` instead o
 
 ## Bitwise operations on `UD30x9`
 
-`UD30x9` exposes a full set of bitwise helpers — `and`, `and2`, `or`, `xor`, `not`, plus `lshift` / `rshift` and their `unchecked_*` siblings. `SD29x9` does **not** expose bitwise operations, on purpose: bit-twiddling on a two's complement representation is rarely what protocol authors mean.
+`UD30x9` exposes a full set of bitwise helpers: `and`, `and2`, `or`, `xor`, `not`, plus `lshift` / `rshift` and their `unchecked_*` siblings. `SD29x9` does **not** expose bitwise operations, on purpose: bit-twiddling on a two's complement representation is rarely what protocol authors mean.
 
 The most common use for these is packing flags or scale-shifting raw bit patterns inside a fixed-point pipeline:
 
@@ -320,7 +320,7 @@ use openzeppelin_fp_math::ud30x9;
 // Mask to keep only the low 64 bits of the raw representation.
 let truncated = ud30x9::wrap(some_value).and(0xFFFFFFFFFFFFFFFF);
 
-// Shift the raw representation right by 9 bits — note this is a bit shift,
+// Shift the raw representation right by 9 bits. Note: this is a bit shift,
 // not a divide-by-2^9, and not a divide-by-10^9.
 let shifted = ud30x9::wrap(some_value).rshift(9);
 ```
@@ -348,7 +348,7 @@ In practice:
 use openzeppelin_fp_math::{ud30x9, ud30x9_convert};
 
 let two = ud30x9_convert::from_u128(2);
-let eight = two.pow(3); // 8.0 — exact for whole-number bases.
+let eight = two.pow(3); // 8.0, exact for whole-number bases.
 
 let half = ud30x9::wrap(500_000_000); // 0.5
 let q = half.pow(20); // ≈ 0.000000953... but truncation may bias the result.
@@ -364,9 +364,9 @@ For small integer exponents over operands that are not far from `1.0`, `pow` is
 
 `SD29x9::min()` returns `-2^127`. There is no representable `+2^127`, so several operations abort when called on `min()`:
 
-- `abs(min())` — aborts with `EOverflow`.
-- `negate(min())` — aborts with `EOverflow`.
-- `wrap(2^127, true)` is fine (it produces `min`); but `wrap(2^127, false)` aborts with `EOverflow`. There is no way to construct `min` via `wrap`; use `min()` directly.
+- `abs(min())`: aborts with `EOverflow`.
+- `negate(min())`: aborts with `EOverflow`.
+- `wrap(2^127, true)` is fine (it produces `min`), but `wrap(2^127, false)` aborts with `EOverflow`. There is no way to construct `min` via `wrap`. Use `min()` directly.
 
 Most protocol code never sees `min()`. If your design naturally produces values near the signed-integer boundary, plan for it explicitly:
 
@@ -387,8 +387,8 @@ public fun safe_negate(x: sd29x9::SD29x9): sd29x9::SD29x9 {
 
 `UD30x9::mod` is straightforward: it is the unsigned remainder, always non-negative. `SD29x9` exposes **two** remainder functions because the signed semantics differ:
 
-- **`rem(x, y)`** — truncating remainder. The magnitude is `abs(x) % abs(y)`, and the sign of the result follows the dividend `x`. `rem(-7, 3) = -1`.
-- **`mod(x, y)`** — Euclidean remainder. Always non-negative; satisfies `0 <= mod(x, y) < abs(y)`. `mod(-7, 3) = 2`.
+- **`rem(x, y)`**: truncating remainder. The magnitude is `abs(x) % abs(y)`, and the sign of the result follows the dividend `x`. `rem(-7, 3) = -1`.
+- **`mod(x, y)`**: Euclidean remainder. Always non-negative. Satisfies `0 <= mod(x, y) < abs(y)`. `mod(-7, 3) = 2`.
 
 Most protocol code wants `mod` (Euclidean), because it gives a stable representative of the residue class regardless of the dividend's sign. `rem` is the right choice when you specifically want the remainder to follow the sign of the dividend (e.g., to preserve sign in a pipeline of signed adjustments).
 
@@ -435,7 +435,7 @@ public fun quote_swap_with_fee(
     let effective_in = amount_in.sub(fee);
 
     // Constant-product output, rounded toward zero (in the user's favor as the
-    // taker, against the user as a fee recipient — model your protocol explicitly).
+    // taker, against the user as a fee recipient. Model your protocol explicitly).
     reserve_out.mul_trunc(effective_in).div_trunc(reserve_in.add(effective_in))
 }
 
diff --git a/content/contracts-sui/1.x/index.mdx b/content/contracts-sui/1.x/index.mdx
index 37588ddd..7b58f54c 100644
--- a/content/contracts-sui/1.x/index.mdx
+++ b/content/contracts-sui/1.x/index.mdx
@@ -31,7 +31,7 @@ mvr add @openzeppelin-move/integer-math
 mvr add @openzeppelin-move/fixed-point-math
 ```
 
-You only need the dependencies your app actually uses — add what you need and drop the others.
+You only need the dependencies your app actually uses. Add what you need and drop the others.
 
 ### 3. Verify `Move.toml`
 
@@ -77,7 +77,7 @@ sui move test
 ## Picking a package
 
 - Need integer arithmetic with safe overflow and explicit rounding? Use [Integer Math](/contracts-sui/1.x/math).
-- Need fractional values — prices, fees, rates, signed deltas? Use [Fixed-Point Math](/contracts-sui/1.x/fixed-point).
+- Need fractional values like prices, fees, rates, or signed deltas? Use [Fixed-Point Math](/contracts-sui/1.x/fixed-point).
 - Need controlled transfer of admin/treasury/upgrade capabilities? Use [Access](/contracts-sui/1.x/access).
 
 The packages compose. A typical protocol module imports `openzeppelin_math` for share math, `openzeppelin_fp_math` for rate and fee math, and `openzeppelin_access` for the admin capability that governs both.
diff --git a/content/contracts-sui/1.x/math.mdx b/content/contracts-sui/1.x/math.mdx
index e2c7e88a..85094d69 100644
--- a/content/contracts-sui/1.x/math.mdx
+++ b/content/contracts-sui/1.x/math.mdx
@@ -3,7 +3,7 @@ title: Integer Math
 ---
 
 <Callout type="warn">
-The example code snippets used in this guide are experimental and have not been audited. They simply help exemplify usage of the OpenZeppelin Sui Package.
+The example code snippets used in this guide are experimental and have not been audited. They are meant to illustrate usage of the OpenZeppelin Sui Package.
 </Callout>
 
 The `openzeppelin_math` package is the numeric foundation for OpenZeppelin Contracts for Sui. It provides deterministic arithmetic across unsigned integer widths, explicit rounding controls, and helpers for decimal normalization.
@@ -96,7 +96,7 @@ In May 2025, a single flawed overflow check in a shared math library led to the
 
 ## Rounding as a protocol decision
 
-Every function that divides, shifts, or roots a value requires a `RoundingMode` argument. There is no default, and the choice is not cosmetic. Rounding direction determines which side of a transaction absorbs fractional remainders, and in modern day blockchain applications, that determines where value leaks.
+Every function that divides, shifts, or roots a value requires a `RoundingMode` argument. There is no default, and the choice is not cosmetic. Rounding direction determines which side of a transaction absorbs fractional remainders. In practice, that determines where value leaks.
 
 ### The vault example
 
@@ -203,7 +203,7 @@ use openzeppelin_math::u256::{mul_div};
 let output = mul_div(reserve_out, amount_in, reserve_in + amount_in, rounding::down());
 ```
 
-Instead of carrying out any multiply-then-divide operation manually (e.g., `(a * b) / c`), you can simply use `mul_div` instead. The manual version overflows when `a * b` exceeds the type range, even if the final result after division would have been safe.
+Instead of carrying out any multiply-then-divide operation manually (e.g., `(a * b) / c`), use `mul_div`. The manual version overflows when `a * b` exceeds the type range, even if the final result after division would have been safe.
 
 ### `mul_shr`