cfKanban Admin

Use this Skill with a verified current Principal and scope: read /api/v1/me, distinguish is_owner from direct management_grants, and check the target resource's allowed_actions. Ordinary writer access is not administration. Read the relevant section of English or 简体中文 when a task needs detailed inputs or recovery. Choose one language; ordinary operations do not require loading the whole guide.

Principal names (schema 8 and later) are unique across the Instance. Creation and rename trim outer whitespace and store NFKC-normalized text; uniqueness uses non-locale toLowerCase(). Both display text and comparison key must contain 1–128 Unicode code points. Allow Unicode letters, marks, numbers and _, -, ·; reject internal whitespace, default-ignorable characters, other symbols and exact reserved keys admin, administrator, owner, system, 管理员, 所有者, 系统. PRINCIPAL_DISPLAY_NAME_CONFLICT requires another user-chosen name; do not silently append a suffix. A display name never grants access, and all writes still use stable Principal IDs.

Start with the management goal

Examples: “Create a DemoProject Project in Product”, “Invite someone to DemoProject as a reader”, “Show who can access DemoProject”, or “Show usage and attachment capacity”. Expect a verified container, safely delivered invitation, access listing, or usage report respectively; one request does not authorize the other actions. Read Common Owner requests in the workflow reference for examples and outcomes.

The audience includes the single Deployment Owner and scoped Workspace/Project administrators. Application access and container management follow the current scope; quotas and attachment capacity remain Owner-only. Enabling cloud attachment storage or changing deployed request-rate settings belongs to cfkanban-deploy; ordinary Issue status, Comments, and completion belong to cfkanban.

What this Skill can do

• Inspect and manage authorized containers and effective members; appoint scoped administrators where permitted and rename fixed status display labels.
• Create/revoke scoped Project Invites; Owner additionally creates Principal Recovery Invites. Inspect permitted status without exposing Invite codes.
• Change/revoke ordinary Project Grants within scope. Owner additionally lists instance Principals, participant Credentials, and audit events and revokes participant Credentials.
• Owner only: rotate the Owner Credential through a pending-secret workflow that never exposes either secret.
• Owner only: add another device with an independent Credential, list devices, name or rename active devices, and revoke one other device (schema 12+). An existing Owner device or a supported Owner admin Web session approves the new environment’s non-secret request. Explicit replacement of an existing local identity preserves a private restoration slot; no long-lived secret is copied between environments.
• Owner only: read or edit the public bilingual homepage notice, including restoring its fallback (schema 11+).
• Owner only: read instance usage, request cache-aware Cloudflare refresh on every usage query, and inspect or change Owner-selected attachment capacity.
• Owner only: configure one Project's Public Join policy and active resource limits; inspect deployed request-rate settings.
• Owner only: change the preferred API origin after a credential-free probe and open an Owner-scoped Web session.

This Skill uses the application REST API only. Use cfkanban for daily Issue work and cfkanban-deploy for Cloudflare resources, deployment, migrations, Instance upgrades, or total Owner Credential loss.

Scoped administration (schema 9+)

Every Workspace and Project can have zero or more administrators. Owner appoints Workspace administrators; Owner or the parent Workspace administrator appoints Project administrators. Neither role appoints or removes peers. Owner retains recovery and final control; there is no last-local-administrator restriction.

Workspace administrators can rename their active Workspace, create Projects, manage all current/future child Projects, archive/restore child Projects, and manage their ordinary members. Project administrators can rename their active Project, edit context and fixed status display names, and manage ordinary reader/writer members. Neither can create/archive/restore a Workspace. Project administrators cannot archive/restore their Project. Public Join, quotas, global usage/audit, permanent purge, identity recovery, and other people's Credentials/Passkeys remain Owner-only. Deployment authority is unchanged.

Management and ordinary Grants are independent sources. Effective access is their union; administrators project to writer for Issue operations but writers cannot manage. Read paginated effective members and show inherited and direct sources; revoking one source does not remove another. Administrators count toward each public Project's Principal quota once per Principal. Granting a Workspace administrator atomically fails if any affected Project would gain an over-limit member; never work around this by granting only some child Projects.

Non-Owner normal Invites name exactly one managed Project and an explicit reader/writer role. No Invite or Public Join grants administration. Each such Invite binds the exact issuing management grant ID/generation: revocation permanently invalidates unredeemed Invites, even after regrant or when another management source survives. Redeemed memberships remain. Local administrators cannot inspect recovery Invites or Invitations containing any unmanaged target. Refresh /me and resource permissions after access failures; never request Owner credentials as a workaround.

Intent-first user experience

Treat “Create my first cfKanban board” as sufficient to begin. Verify current identity, management scope, and state, reuse names already supplied, and collect any missing Workspace/Project display names together. The server creates UUIDs; never ask for or derive container keys. Carry the authorized task through to a verified usable board without requiring API terminology from the user. Routine previews and confirmations follow the user's and host's rules; this Skill adds no approval round for an already authorized ordinary write.

When a concrete Project is verified during administration from a user working directory, reuse the cfkanban Skill's scope inspect-directory result or route there once for directory association. A confirmed Git worktree without saved scope gets one brief optional offer; non-Git directories get no proactive offer, and unknown/unavailable detection does not justify guessing. Use the verified Project identifiers if the user accepts; creation or administration itself never authorizes saving the file. Existing associations or a declined offer suppress repeat prompts, and directory setup never blocks the administration goal.

Opening cfKanban means a verified local workbench or authenticated online page. For browser delivery, resolve the trusted instance with web resolve and verify /api/v1/me; an explicit unknown instance/origin never falls back to another. For ordinary Project/Issue opening, follow the cfkanban Skill's shared host-capability selection and honor an explicit sidebar, browser or online request. Use the following local-browser guidance only when that surface is selected. The local workbench verifies a single recommended scope target automatically; multiple targets remain selectable in the UI. It offers project switching, Kanban/list, quick priority/status/assignee edits and Issue details, comments and completion. Use explicit mode:"online" for the full WebUI, management/customization, or when requested; its delivery uses the existing Browser Launch. Keep the original mode on failure and explain the concrete recovery instead of silently switching. Read the local/online workflow before opening: English / 简体中文.

When browser delivery is selected, honor the requested browser. When trusted host context identifies Codex App and an IAB navigation tool is available, prefer local mode in IAB with delivery:"host_browser"; do not infer the host from environment variables. On an unverified delivery path, run web preflight and verify the requested browser and visible success page. Keep the probe tab handle/ID and navigate that same tab to the one-time relay URL; create a tab only when no reusable probe tab remains. Reuse successful preflight evidence while the task and delivery environment stay unchanged. Other hosts with verified browser tab control can use the same host_browser flow; a plain system_browser opener cannot guarantee tab reuse. An opener executable or navigation tool alone does not prove reachability. Consume the exact one-time relay event immediately in the chosen browser, without repeating or persisting its URL; keep the local process alive while the workbench is open. Verify the displayed Principal and Project after navigation. A browser failure alone does not require a new identity. Copy Issue IDs/URLs or raw description/comment Markdown; the UI does not send to Agent sessions or build a duplicate handoff summary.

Online Web Session lifetime

Browser Launch remains a five-minute, single-use capability. On supporting Services, Agent-launch and Passkey Sessions start with eight hours and may renew on real foreground mouse, keyboard, or touch activity: eight hours after renewal, at most one actual extension per Session every 30 minutes, capped at seven days from its original creation. Identity, source, and scope stay unchanged, including narrow Owner or Workspace Sessions. Background work, refresh, and focus checks do not renew. Only the Web's Cookie-only, same-origin/CSRF endpoint can renew; never use a Skill Bearer request for this. Missing Session renewal metadata means the old fixed eight-hour behavior, regardless of local Skill version.

Expiry or source revocation requires fresh sign-in. Keep the original page open for any offered text draft, let the user explicitly restore or copy and review it, and never replay a write. Drafts stay in page memory, exclude credentials/capabilities/attachments, and are lost on refresh/close or explicit sign-out. Read the details in English or 简体中文.

Usage requests

Treat “How much storage are we using?”, “查看使用情况”, or “还剩多少附件容量” as Owner usage requests. Verify the trusted instance and Owner, then call POST /api/v1/admin/usage/refresh with {mode:"manual"} on every query; no browser launch or preliminary GET is needed. This shares the Web refresh path and server-side 15-minute cache, 60-second attempt cooldown, and concurrent-collection guard. Both accepted modes use the same cache policy; manual is not a force bypass. Do not poll or change limits, enable analytics, or configure credentials as a side effect of inspecting usage. Use GET only when the user explicitly wants the stored snapshot without a collection attempt.

Summarize attachment reservations and the Owner-selected limit separately from D1/R2 metrics. Distinguish an unset policy from explicit unlimited capacity, and unknown metrics from zero. Remaining application capacity can be calculated only for a configured finite limit; it is not remaining Cloudflare free allowance. Use one short update time, mark stale or unavailable data, and provide exact observation/windows only when relevant. See the Owner usage section in English or 简体中文 for request examples and availability handling.

Homepage notice requests

For “Change the homepage description” or “恢复首页默认说明”, use GET/PATCH /api/v1/admin/homepage-settings through api request. Verify the deployed schema 11+ endpoint and the unique Owner's instance control scope; scoped administrators and project-scoped Owner Sessions cannot use it. Local Skill availability does not prove server support, and an unavailable endpoint never authorizes an upgrade. Read the current setting/version, PATCH both notice_en and notice_zh_cn with expected_version and one Idempotency Key, then read back. Each value is public plain text, at most 500 Unicode code points after trim; null or trimmed-empty text restores fallback. Read the examples and conflict handling in English or 简体中文.

Command entry point

Run commands from this Skill directory:

node scripts/cfkanban-tool.mjs help
node scripts/cfkanban-tool.mjs <command>

Read help once for the installed release, and again after an update or when a command's inputs are unclear. It returns the available commands, effects, input fields, and output classifications. Other commands receive structured JSON on stdin. Use api request for ordinary application operations; it refuses Invite and Browser Launch creation because those responses require dedicated delivery. Never put a Credential into the input: owner rotate-credential reads current and pending secrets internally, verifies the replacement through /api/v1/me, and only then promotes it.

Task-to-command map

Goal	Command or REST operation	Required handling
Verify identity and management scope	state inspect, then api request → GET /api/v1/me	Read is_owner, management_grants, and target allowed_actions; require Owner only for Owner-exclusive operations. Names and data-plane writer never grant management.
Create the first usable board	create one Workspace, create one Project, read both back, then web launch with an admin target	Create using display names and read back server-generated UUIDs; names are not unique identifiers.
Manage Workspaces and Projects	Workspace/Project GET/POST/PATCH/DELETE plus single-resource commands/restore	Use server-generated UUIDs, CAS where defined, one Idempotency Key per atomic write, and readback.
Permanently remove an archived container	GET .../purge-preview, then POST .../commands/purge	Owner only; inspect counts and shared invitations, require exact name/version/digest, one Idempotency Key; archived empty Workspace or archived Project only. Read the purge workflow first.
Rename fixed status labels	GET .../statuses, PATCH .../statuses/{status_key}	Only display names change; stable keys, order, category, and terminal meaning do not.
Create or revoke an Invite	invite create; read/revoke through api request	Always submit explicit Project roles. Default clipboard delivery keeps the complete Invite URL out of stdout.
Recover a participant	invite create with kind=principal_recovery	Bind the exact Principal ID and immutable `rotation
Manage effective members	GET .../projects/{project_id}/members; Project Grant endpoints	Scope-authorized; show every source and remaining access after removing one source. Instance Principal/Credential/Passkey endpoints remain Owner-only.
Manage administrators	GET/POST .../administrators, DELETE .../administrators/{administrator_id}	Workspace administrators: Owner writes. Project administrators: Owner or parent Workspace administrator writes. POST needs principal_id and expected_version (first 0; regrant current revoked row version); DELETE needs current version.
Rotate Owner Credential	credential prepare with purpose=owner_rotation, then owner rotate-credential	Keep the same pending secret/Idempotency Key on uncertainty; promotion follows verified /me readback.
Connect another Owner device	new environment: owner-device prepare; existing environment: owner-device approve; new environment: owner-device verify	Read the Owner devices workflow first. Transfer only the non-secret request; verify the exact instance, Owner and fingerprint. Requires deployed schema 12+.
Restore the previous local identity	owner-device restore-previous	Use the exact instance and expected current Principal/Credential IDs; verify the previous Credential before switching, preserve the Owner for recovery, and reuse the same input after interruption.
Inspect/revoke an Owner device	owner-device list, owner-device revoke	Paginate with next_cursor; revoke by exact Credential ID. Cannot revoke the current source or last active Owner API Credential; independent Passkeys and other devices survive.
Configure Public Join	GET/PUT/DELETE /api/v1/admin/projects/{project_id}/public-join	Use project.version as expected_version, never policy_version; disabling does not revoke existing Grants.
Configure active quotas	GET/PATCH /api/v1/admin/projects/{project_id}/resource-limits	Use the returned project.version; limits are explicit, and 50/500/50 is a suggestion rather than a silent default.
Configure attachment capacity	GET/PATCH /api/v1/admin/attachment-settings	Owner only; read version, then {limit_bytes: positive-safe-integer-or-null, expected_version} with one Idempotency-Key and readback. Null explicitly means unlimited; unconfigured pauses new uploads.
Read or refresh Owner usage	GET /api/v1/admin/usage; POST /api/v1/admin/usage/refresh	Refresh body `{mode:"stale"
Inspect request-rate settings	GET /api/v1/admin/rate-limit-settings	Read-only here; changing Worker bindings belongs to cfkanban-deploy.
Check deployed and available releases	GET /api/v1/admin/release-updates; CLI admin updates show	Owner instance control only. Distinguish current Worker version, stable and bounded recent prereleases; show cache/check status. The site cannot inspect local Skills. Checking does not install or deploy; follow separate immutable release plans.
Configure upgrade announcements	GET/PATCH /api/v1/admin/upgrade-notification-settings; CLI admin upgrade-notification show/configure	Owner instance control only; use returned CAS version, a stable key and readback. Default off. Announcements follow verified forward upgrades only; same-version redeploys, rollbacks and local Skills updates do not announce.
Verify or recover an upgrade announcement	GET /api/v1/admin/notifications/upgrade-releases/{release_version}; CLI admin upgrade-notification release/publish	Reuse the exact retained deployment event, caller and key. A lookup alone does not prove an uncertain original write. Announcement failure does not undo a verified upgrade. Never fabricate a success event from a site version string.
Restore content or a container	Stable resource read or explicit deleted=only, then one restore endpoint	Before container restore, show every enabled Public Join policy that will resume.
Change preferred origin	origin rebind-check, then GET/PUT /api/v1/admin/instance-origin	Probe the candidate without a Credential, use expected version, then cross-read both origins.
Open Owner Web	web resolve, /me, then web open with mode:"online" and an admin target	Verify Owner; default to Overview. Preflight the chosen delivery path; use system_browser for a verified matching default, otherwise host_browser.
Inspect audit history	GET /api/v1/admin/audit-events	Use bounded pagination; when the task has a known scope, pass one immutable project_id and/or `stream=domain

The complete request and recovery guide is references/owner-workflows.md.

Audit reads without project_id or stream deliberately cover the whole Instance and both streams. Reuse next_cursor only with the exact same filters; changing either filter starts a fresh read.

Classify an event's lifecycle resource by subject.type and subject.id. authorized_via and grant_id are historical authorization evidence: a participant's Issue write can carry the Project Grant that authorized it, while a Grant-management event can carry that same ID for the Grant subject. Never use grant_id alone to select Grant lifecycle events.

First-use workflow after deployment

1. Verify local state, trusted origin, /api/v1/me, and is_owner=true.
2. Reuse explicit names and any explicitly selected existing Workspace. Ask together for missing display names; resolve duplicate existing names before writing.
3. Create a Workspace only when requested or needed for the first board, read back its UUID, then create the requested Project under that UUID with a separate Idempotency Key and read it back.
4. Create an Owner Browser Launch only after both resources exist. Deployment does not create a default Workspace, Project, Label, Grant, or Issue.
5. Offer, but do not silently perform, the next independent actions: create the first Issue with cfkanban, create an explicit-role Invite, or configure Public Join with explicit quotas.

Ordinary operations

Verify trusted local identity and the target's current state. Reuse unchanged identity/scope evidence from the current task; refresh the resource version before CAS writes. Present exact target and consequences for security-sensitive, public-access, or irreversible changes. Except the derived usage-cache refresh documented above, perform each atomic write with its own Idempotency Key, then read back the resource; Owner may inspect audit events when checking authorization or lifecycle history. Scoped administrators use their permitted resource/member readback. A multi-call goal is not a transaction: report earlier commits separately if a later call fails.

Contract and stop conditions