Skip to content

docs(lez): Extensions section with admin-authority and extension-library guides#355

Draft
mmlado wants to merge 1 commit into
logos-co:mainfrom
mmlado:docs/admin-authority-rfp-001
Draft

docs(lez): Extensions section with admin-authority and extension-library guides#355
mmlado wants to merge 1 commit into
logos-co:mainfrom
mmlado:docs/admin-authority-rfp-001

Conversation

@mmlado

@mmlado mmlado commented Jun 24, 2026

Copy link
Copy Markdown

Summary

Adds two pages under a new docs/lez/extensions/ folder, plus an "Extensions" entry in docs/lez/SUMMARY.md:

  • admin-authority.md, integration guide for app developers. Covers annotation, gating, AdminCandidate (Signer / PDA), initialization window risk, transfer, renounce, IDL verification, security notes.
  • build-a-spel-extension-library.md, author guide for the generic [package.metadata.spel] discovery mechanism. Covers two-crate layout, metadata fields, marker / gate macros, multi-extension stacking, common troubleshooting.

Context

These pages document the user-facing surface of RFP-001 (admin-authority library) and the framework mechanism it relies on. The framework mechanism, a generic [package.metadata.spel] extension scanner in spel-framework-core::idl_gen, is delivered as a separate PR against logos-co/spel (see companion PR). These docs are the consumer-facing complement.

Future extension libraries (e.g. RFP-002 freeze-authority) can ship without any framework change, so the "Build a SPEL extension library" page is written generically to serve as the canonical author guide for any future extension.

Why a new extensions/ folder

lez/ already groups capabilities by folder (get-started/, transfer-tokens/). Extension libraries are a new capability class. Placing both pages under lez/extensions/ mirrors the existing structure and keeps consumer and author guides discoverable side-by-side.

Companion repositories

Open questions for maintainers

  1. Folder name. Used extensions/ for brevity. Alternatives: extension-libraries/, program-extensions/, access-control/ (too narrow for the generic guide).
  2. Page placement. Both under lez/. The author guide could arguably sit under build-an-app/ instead. Open to splitting if you prefer.
  3. Cross-linking. The pages reference each other directly. No links from the broader lez/ or build-an-app/ READMEs yet, happy to add.

Style notes

Pages follow the existing GitBook hint-block convention ({% hint style="warning" %} for the draft-status banner and the initialization-window warning). Heading depth and table style match docs/build-an-app/tutorials/.

Relates to

…library guides

Two new pages under docs/lez/extensions/:

  - admin-authority.md: integration guide for app developers. Covers
    annotation, gating, AdminCandidate (Signer / PDA), initialization
    window, transfer, renounce, verification, security notes.
  - build-a-spel-extension-library.md: author guide for the generic
    [package.metadata.spel] discovery mechanism. Covers two-crate
    layout, metadata fields, marker / gate macros, multi-extension
    stacking, troubleshooting.

SUMMARY.md updated with new section.

Relates to: RFP-001 (logos-co/rfp#46)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant