@wardby/cli 0.3.0 → 0.4.1

package/docs/getting-started-identity-provider.md

@@ -54,23 +54,25 @@ access tokens for that audience.
 
 Create these scopes in the provider:
 
-| Scope                 | Capability                                                        |
-| --------------------- | ----------------------------------------------------------------- |
-| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.     |
-| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships. |
-| `runs:trigger`        | Start agent runs.                                                 |
-| `tools:write`         | Create, attach, and manage tools.                                 |
-| `datastore:write`     | Create, attach, query, and modify datastores.                     |
-| `secrets:write`       | Create, attach, rotate, and remove secret bindings.               |
-| `webhooks:write`      | Create and manage webhook triggers.                               |
-| `budget_groups:write` | Create and manage shared budget groups.                           |
-| `packages:approve`    | Approve coding agents' package allowlists.                        |
-| `services:manage`     | Create, update and delete coding-run service catalog entries.     |
-| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.         |
-| `memory:write`        | Set and delete agent memory entries.                              |
+| Scope                 | Capability                                                         |
+| --------------------- | ------------------------------------------------------------------ |
+| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.      |
+| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.  |
+| `runs:trigger`        | Start agent runs.                                                  |
+| `tools:write`         | Create, attach, and manage tools.                                  |
+| `datastore:write`     | Create, attach, query, and modify datastores.                      |
+| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                |
+| `webhooks:write`      | Create and manage webhook triggers.                                |
+| `budget_groups:write` | Create and manage shared budget groups.                            |
+| `packages:approve`    | Approve coding agents' package allowlists.                         |
+| `services:manage`     | Create, update and delete coding-run service catalog entries.      |
+| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.          |
+| `memory:write`        | Set and delete agent memory entries.                               |
+| `admin:view`          | Read every owner's runs through the admin viewer API; admins only. |
+| `models:admin`        | Add, override, disable and reset model catalog entries.            |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all twelve in the provider even when
+may request every advertised scope. Define all fourteen in the provider even when
 policy grants a particular client or user only a subset. Ensure granted scopes
 are emitted in the access token's `scope` or `scp` claim; defining them only in
 the provider UI is not sufficient.
@@ -82,23 +84,32 @@ request every advertised scope may fail with `invalid_scope`.
 `services:manage` was added after `memory:write`. When you upgrade an existing
 deployment, define it in the provider too, for the same reason.
 
+`admin:view` was added after `services:manage`. When you upgrade an existing
+deployment, define it in the provider too and map it like `agents:admin`;
+otherwise clients that request every advertised scope fail with `invalid_scope`.
+
+`models:admin` was added after `admin:view`. When you upgrade an existing
+deployment, define it in the provider too; otherwise clients that request
+every advertised scope fail with `invalid_scope`.
+
 ### Wardby roles
 
-A scope only delegates. `agents:admin`, `packages:approve` and `services:manage`
-take effect only for a caller who also holds a Wardby role that grants them:
+A scope only delegates. `agents:admin`, `packages:approve`, `services:manage`,
+`admin:view` and `models:admin` take effect only for a caller who also holds a Wardby role that grants them:
 
-| Wardby role        | Grants                                                                                        |
-| ------------------ | --------------------------------------------------------------------------------------------- |
-| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve` and `services:manage` |
-| `package-approver` | `packages:approve` (package allowlist and policy approval)                                    |
-| `service-manager`  | `services:manage` (coding-run service catalog changes)                                        |
+| Wardby role        | Grants                                                                                                                                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)) and `models:admin` (model catalog) |
+| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                |
+| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                    |
+| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                           |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
 
 ```dotenv
 AUTH_ROLE_CLAIM=groups   # claim name or dotted path
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
 ```
 
 Wardby looks up `AUTH_ROLE_CLAIM` in two steps:
@@ -146,20 +157,20 @@ their next token.
 
 Provider examples:
 
-- **Okta** (custom authorization server): create three groups, `wardby-admin`,
-  `wardby-packages` and `wardby-services`. Add a `groups` claim to the access
-  token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager`.
+- **Okta** (custom authorization server): create four groups, `wardby-admin`,
+  `wardby-packages`, `wardby-services` and `wardby-models`. Add a `groups` claim
+  to the access token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve` and `services:manage`.
-- **FusionAuth:** create three application roles, `admin`,
-  `package-approver` and `service-manager`. They appear in the access token's
-  top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
-  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager`.
-- **Keycloak:** create realm roles such as `wardby-admin`, `wardby-packages`
-  and `wardby-services`. Realm roles appear under `realm_access.roles`. Set
-  `AUTH_ROLE_CLAIM=realm_access.roles` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager`.
+  `agents:admin`, `packages:approve`, `services:manage`, `admin:view` and `models:admin`.
+- **FusionAuth:** create four application roles, `admin`,
+  `package-approver`, `service-manager` and `model-manager`. They appear in the
+  access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
+  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager`.
+- **Keycloak:** create realm roles such as `wardby-admin`, `wardby-packages`,
+  `wardby-services` and `wardby-models`. Realm roles appear under
+  `realm_access.roles`. Set `AUTH_ROLE_CLAIM=realm_access.roles` and
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
   For client roles, use `resource_access.<client-id>.roles`. The
   [local Keycloak harness](../deploy/keycloak-test/README.md) sets this up.
 - **Auth0:** add the user's roles to the access token as a namespaced custom
@@ -206,7 +217,7 @@ AUTH_JWKS_URI=https://identity.example.com/your-tenant/.well-known/jwks.json
 AUTH_AUDIENCE=https://wardby.example.com/mcp
 # Optional: Wardby roles (see "Wardby roles" above).
 AUTH_ROLE_CLAIM=groups
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
 ```
 
 Copy `AUTH_ISSUER` exactly from the token's `iss` claim or the provider's
@@ -242,7 +253,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all ten Wardby scopes.
+- `scopes_supported` contains all fourteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.

package/docs/getting-started.md

@@ -123,8 +123,22 @@ Coding agents require the stronger boundary described in
 worker image, trusted coding proxy, and either Docker or Kubernetes as the job
 launcher. Run `wardby coding preflight` before enabling a production repository.
 
+## Your first agents
+
+[Agent recipes](agent-recipes.md) gives two complete, copyable setups: an
+architecture keeper and a builder per language. They go beyond the quickstart,
+which runs native agents only. They require Wardby 0.4.0 or later. They need the
+GitHub App, worker image, and job launcher from
+[Coding-agent setup](coding-agent-setup.md). Their event triggers need GitHub to
+reach your instance at a public HTTPS URL.
+
+The assistant the quickstart connected can walk you through either recipe. Ask it
+"Set up the Wardby architecture keeper for this repository" or "Set up a Wardby
+builder for this repository"; it follows the `agent-recipes` help article.
+
 ## Next steps
 
+- [Agent recipes](agent-recipes.md)
 - [Runtime architecture](architecture-runtime.md)
 - [Coding-agent setup](coding-agent-setup.md)
 - [Bring your own identity provider](getting-started-identity-provider.md)