@yargote/artifacts-cli 0.1.0-beta.7 → 0.1.0-beta.8

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.7
+npm install --global @yargote/artifacts-cli@0.1.0-beta.8
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.7
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.8
 artifacts --version
 ```
 
@@ -22,23 +22,26 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.7 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.7 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.8 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.8 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
 
 ## Complete first use
 
+Check `artifacts --help` for saved-connection support. With an older package that requires a server on every command, keep `ARTIFACTS_SERVER` set to the selected REST resource.
+
 An existing Artifacts account is required. Select the REST OAuth resource, which is the API origin without `/mcp`. When upgrading an older deployment, complete the [API migration](../../docs/deployment.md#migrate-the-api-hostname) before using the address below.
 
 ```sh
-export ARTIFACTS_SERVER='https://artifacts-api.yersonargotev.workers.dev'
-artifacts login
+artifacts login --server 'https://artifacts-api.yersonargotev.workers.dev'
 artifacts whoami
 ```
 
-Login opens browser authorization. After you approve access, `whoami` prints JSON with your user ID and scopes. Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine.
+Login opens browser authorization. After you approve access and the CLI verifies your identity, it saves the resolved REST resource in private state. A new terminal can run `artifacts whoami` without a server option or environment variable. It prints JSON with your user ID and scopes.
+
+Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine. This manual flow saves the connection only after identity verification succeeds.
 
 Create `snapshot.json`:
 
@@ -82,21 +85,33 @@ Run `artifacts logout` before uninstalling if you want to clear credentials. Uni
 
 Skills, help, and version commands work without a server or login. Skills commands do not read credentials or create private state. They accept and ignore global `--server` and `--state-dir` values, including their environment defaults.
 
-`--server RESOURCE` selects the exact canonical REST OAuth resource. `ARTIFACTS_SERVER` supplies the same value. Use the configured `API_URL` origin to call REST under `/v1`. The CLI has no production default and does not rewrite the supplied URL. Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
+`--server RESOURCE` overrides `ARTIFACTS_SERVER`, which overrides the connection saved by the last successful login in the selected state directory.
+
+An ordinary command override applies to that command and does not replace the saved connection. A later successful login replaces it with the verified canonical REST resource. A failed login to another server preserves the previous selection and its credentials.
+
+Login also accepts an MCP resource that advertises its REST resource. Use the configured `API_URL` origin to call REST under `/v1`.
+
+Without an override or saved connection, run `artifacts login --server RESOURCE` first. The CLI has no production default and does not rewrite the supplied URL. Existing installations keep their exact-resource credentials, but must complete a successful login to save a connection.
+
+Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
 
 A hostname change requires a new `artifacts login --server RESOURCE`. Credentials and retained operations remain bound to their exact original resource. Do not move an old operation file to the new resource or redirect its bearer requests.
 
-`--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
+`--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Each state directory has its own saved connection and credential profiles. Credentials and the saved connection share one private database, separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
 
 HTTPS is required except for HTTP on the exact loopback hosts `localhost`, `127.0.0.1`, and `[::1]`. Server URLs cannot contain credentials, a query, or a fragment.
 
 ## Authentication
 
-`artifacts login --server RESOURCE` verifies protected-resource metadata, registers a public native OAuth client, and opens browser authorization with PKCE. `--no-browser` prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
+`artifacts login --server RESOURCE` verifies protected-resource metadata. If a resource advertises `artifacts_rest_resource`, the relation may name the same resource or one distinct REST resource. Login verifies metadata for a distinct resource and prints its REST URL to stderr. The distinct resource may omit the relation or name itself, but cannot name another resource. After identity verification, login saves that REST URL for later commands. An existing `ARTIFACTS_SERVER` still overrides it. Unset the variable to use the saved connection. Login anonymously checks `<resource>/v1/identity` before registering a public native OAuth client and opening browser authorization with PKCE. This check confirms REST compatibility. Login verifies your identity again with the received token before atomically saving credentials and the connection.
+
+Errors identify the phase, method, endpoint, and HTTP status when a response exists. Network failures have no HTTP status. If the compatibility check fails, confirm the configured REST URL with your service administrator. A valid MCP metadata document alone does not establish REST compatibility.
+
+`--no-browser` runs the same checks and prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
 
 `artifacts whoami` returns the verified user, session, OAuth client, and scopes.
 
-`artifacts logout` clears local credentials and attempts to revoke the refresh token. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
+`artifacts logout` clears local credentials and attempts to revoke the refresh token. It preserves the saved connection, so `artifacts login` can reuse the server without another URL. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
 
 `ARTIFACTS_ACCESS_TOKEN` supplies an access token for automation. It does not require local login. Tokens are never command arguments or retained operation fields.
 
@@ -110,12 +125,14 @@ The private `credentials.sqlite` file stores credentials. The separate `credenti
 artifacts login [--no-browser]
 artifacts logout
 artifacts whoami
-artifacts create --snapshot FILE [--project NAME] [--request-id ID]
+artifacts create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
                  [--response full|compact]
 artifacts create --command FILE
 artifacts list [--limit N] [--cursor CURSOR] [--project NAME]
 artifacts projects
 artifacts read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+artifacts read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+               [--out FILE [--quiet]]
 artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
                  [--response full|compact]
 artifacts update [ID] --command FILE
@@ -202,6 +219,18 @@ Every artifact read and list item includes `project`, a name or null. `projects`
 
 Version `0.1.0-beta.4` and earlier parse artifact responses strictly and fail with `invalid_response` against a server that returns `project`. Upgrade the CLI together with the server.
 
+## Slugs
+
+A slug names a page within its project, so `read` can find it without its ID. `create --slug SLUG` sets it. A slug contains 1 to 160 characters of lowercase ASCII kebab-case segments separated by `/`, such as `concepts/rag` or `index`. It is never normalized, and a trailing `.md` is rejected with a hint to remove it. A complete create command file can include the same optional `slug` field.
+
+```sh
+artifacts create --snapshot snapshot.json --project Mi-Wiki --slug concepts/rag
+artifacts read --project mi-wiki --slug concepts/rag
+artifacts read --slug index
+```
+
+A slug is unique within the owner's project, matched by the project's stored spelling. Artifacts without a project share one unfiled namespace, which `read --slug` reads without `--project`. `read` takes exactly one of an ID or `--slug`, and `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId`. A locator with no artifact fails with `not_found`. Every artifact read and list item includes `slug`, a name or null. Version `0.1.0-beta.7` and earlier reject responses that include `slug` with `invalid_response`.
+
 ## Share publication access
 
 These commands are available from `0.1.0-beta.6`. Check installed help for support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.8",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,8 +27,8 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.7",
-    "@yargote/artifacts-client": "0.1.0-beta.7",
+    "@yargote/artifacts-contracts": "0.1.0-beta.8",
+    "@yargote/artifacts-client": "0.1.0-beta.8",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -9,7 +9,7 @@ Use the installed `artifacts` executable. Run `artifacts --help` and read [the c
 
 ## Select the account and resource
 
-Use the resource selected by the user or the existing `ARTIFACTS_SERVER` environment value. Pass `--server RESOURCE` or set `ARTIFACTS_SERVER` for service commands. Skills, help, and version commands work offline without a server or login. Login does not set an implicit default. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
+Use the resource selected by the user. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful login in the selected private state directory. Ordinary command overrides do not replace that connection. Skills, help, and version commands work offline without a server or login. Check installed help for saved-connection support. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
 
 Run `artifacts whoami` before the first mutation when the current identity is not established. Keep the selected resource and owner consistent throughout one operation. If login is needed, use `artifacts login --server RESOURCE`. The user authenticates in the browser. Do not collect their password or read another application's credentials. Never put tokens in command arguments, operation files, logs, or the final reply.
 
@@ -35,6 +35,8 @@ Use `edit` for partial changes that preserve omitted fields. Use `update` for a
 
 When the user names a project for new content, add `--project NAME` to `create`. Run `artifacts projects` first when an existing project may already fit. A name matching an existing project regardless of letter case joins it and keeps the stored spelling. Do not invent a project the user did not ask for. Use `list --project NAME` to find artifacts in a project.
 
+When the user names a page, add `--slug SLUG` such as `concepts/rag` to `create`, and read it later with `read --project NAME --slug SLUG`, or `read --slug SLUG` for an unfiled page, instead of listing for its ID. Omit the `.md` suffix. A `slug_conflict` error names the `artifactId` that already holds the slug in that project.
+
 Use `move ID --project NAME` to file an existing artifact under a project and `move ID --no-project` to remove it from one. A move changes only the project. It creates no revision and leaves the publication unchanged. It is a retained mutation, so recover an uncertain move with `retry`. Verify it with `read` or `list --project NAME`. A project disappears when its last artifact leaves it.
 
 ## Publish deliberately

package/skills/artifacts-cli/references/commands.md

@@ -24,16 +24,17 @@ The published `0.1.0-beta.1` package predates skills commands. Do not assume sup
 ## Authenticate
 
 ```sh
-export ARTIFACTS_SERVER=https://artifacts.example.test/mcp
-artifacts login
+artifacts login --server https://artifacts.example.test/mcp
 artifacts whoami
 ```
 
-Replace the example with the selected resource before executing it. Service commands read `ARTIFACTS_SERVER` or an explicit `--server RESOURCE`. Login does not save a default resource. `--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
+Replace the example with the selected resource before executing it. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful identity-verified login. Ordinary overrides do not replace the saved connection. A later successful login replaces it with the verified REST resource. A failed login to another server preserves the previous connection and its credentials. Check installed help for saved-connection support.
+
+`--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
 
 Use `--no-browser` when the environment cannot open a browser automatically. Open the printed authorization URL and keep the CLI running for its loopback callback. A remote machine's loopback callback must be reachable by the browser used for login. Do not replace the callback with an arbitrary public listener.
 
-`logout` clears local credentials and attempts refresh-token revocation. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
+`logout` clears local credentials and attempts refresh-token revocation. It keeps the saved connection, so a later `artifacts login` can reuse it. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
 
 ## Create a complete snapshot
 
@@ -105,6 +106,20 @@ A project name contains 1 to 80 characters after trimming and NFC normalization,
 
 `move` takes exactly one of `--project NAME` or `--no-project` and prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. It creates no revision and leaves the publication unchanged. Moving to the current project succeeds without change. A lost move response is recovered with `retry REQUEST_ID` like any other retained mutation.
 
+## Name pages with slugs
+
+Check that installed help lists `--slug` before using it.
+
+```sh
+artifacts create --snapshot snapshot.json --project "Mi wiki" --slug concepts/rag
+artifacts read --project "mi wiki" --slug concepts/rag
+artifacts read --slug index
+```
+
+A slug contains 1 to 160 characters of lowercase ASCII kebab-case segments separated by `/`, such as `concepts/rag` or `index`. It is never normalized, and a trailing `.md` is rejected with a hint to remove it. A slug is unique within the owner's project, matched by the project's stored spelling. Artifacts without a project share one unfiled namespace, which `read --slug` without `--project` reads. Every read and list item includes `slug`, a name or null.
+
+`read` takes exactly one of an ID or `--slug`. `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId` in `details`. A locator with no artifact fails with `not_found`. A move keeps the slug and fails with `slug_conflict` when the destination project already uses it.
+
 ## Edit without losing retained data
 
 For a title change, save `changes.json` with only the requested field.
@@ -134,7 +149,7 @@ Command files contain the command itself, without the CLI's retained-operation w
 | `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
 | `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
 
-`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name and an optional `slug`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
 
 ```json
 {

package/src/auth.d.ts

@@ -4,7 +4,10 @@ export declare function login(options: {
     stateDir: string;
     noBrowser: boolean;
     onAuthorizationUrl: (url: string) => void;
-}): Promise<Identity>;
+}): Promise<{
+    resource: string;
+    identity: Identity;
+}>;
 export declare function accessToken(options: {
     resource: string;
     stateDir: string;

package/src/auth.js

@@ -2,13 +2,12 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import * as oidc from 'openid-client';
-import { canonicalResource, identitySchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
-import { z } from 'zod';
+import { canonicalResource, httpErrorSchema, identitySchema, protectedResourceMetadataSchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
+import { HttpError } from '@yargote/artifacts-client';
 import { CredentialStore } from "./credentials.js";
 const networkTimeout = 10_000;
 const callbackTimeout = 180_000;
 const scopes = 'openid profile offline_access artifacts:read artifacts:write artifacts:publish';
-const resourceMetadata = z.object({ resource: z.string(), authorization_servers: z.array(z.string()).min(1) });
 function endpoint(value, issuer) {
     const url = new URL(value);
     const loopback = /^http:\/\/(?:127\.0\.0\.1|\[::1\]|localhost)(?::[0-9]+)?(?:\/|$)/.test(value);
@@ -18,12 +17,34 @@ function endpoint(value, issuer) {
         throw new Error('OAuth endpoints must use the issuer origin');
     return url;
 }
-async function boundedFetch(url, options = {}) {
-    const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(networkTimeout)]) : AbortSignal.timeout(networkTimeout);
-    const response = await fetch(url, { ...options, redirect: 'manual', signal });
+class AuthTransportError extends Error {
+}
+function safeUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return '[invalid endpoint]';
+    }
+}
+function authFailure(context, code, explanation, status) {
+    const message = `${context.phase} ${context.method} ${safeUrl(context.url)}${status === undefined ? '' : ` HTTP ${status}`}: ${explanation}`;
+    return status === undefined ? new AuthTransportError(message) : new HttpError(status, code, message);
+}
+async function boundedFetch(context, options = {}) {
+    const timeout = AbortSignal.timeout(networkTimeout);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await fetch(context.url, { ...options, redirect: 'manual', signal });
+    }
+    catch {
+        throw authFailure(context, 'network_error', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Request timed out' : options.signal?.aborted ? 'Request cancelled' : 'Network request failed');
+    }
     if (response.status >= 300 && response.status < 400) {
-        await response.body?.cancel();
-        throw new Error('Authentication redirects are not allowed');
+        await response.body?.cancel().catch(() => { });
+        throw authFailure(context, 'redirect_refused', 'Redirect refused', response.status);
     }
     const reader = response.body?.getReader();
     const chunks = [];
@@ -36,13 +57,13 @@ async function boundedFetch(url, options = {}) {
                     break;
                 size += chunk.value.byteLength;
                 if (size > 1024 * 1024)
-                    throw new Error('Authentication response is too large');
+                    throw new Error('too large');
                 chunks.push(chunk.value);
             }
         }
-        catch (error) {
+        catch {
             await reader.cancel().catch(() => { });
-            throw error;
+            throw authFailure(context, 'invalid_response', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Response timed out' : options.signal?.aborted ? 'Request cancelled' : 'Cannot read response', response.status);
         }
         finally {
             reader.releaseLock();
@@ -50,31 +71,155 @@ async function boundedFetch(url, options = {}) {
     }
     return new Response(size ? Buffer.concat(chunks) : null, { status: response.status, statusText: response.statusText, headers: response.headers });
 }
-function discoveryOptions(issuer, signal) {
+function jsonResponse(response, context) {
+    if (response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json')
+        throw authFailure(context, 'invalid_response', 'Expected a JSON response', response.status);
+    return response.json().catch(() => { throw authFailure(context, 'invalid_response', 'Invalid JSON response', response.status); });
+}
+async function discoverResource(resource, terminal = false) {
+    const context = { phase: 'resource_metadata', method: 'GET', url: protectedResourceMetadataUrl(resource) };
+    const response = await boundedFetch(context);
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'Resource metadata service failed' : 'Cannot discover the protected resource. Confirm the configured REST URL', response.status);
+    const document = await jsonResponse(response, context);
+    const parsed = protectedResourceMetadataSchema.safeParse(document);
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid protected resource metadata', response.status);
+    if (parsed.data.resource !== resource)
+        throw authFailure(context, 'invalid_response', 'Protected resource metadata does not match the exact server URL', response.status);
+    if (terminal && parsed.data.artifacts_rest_resource !== undefined && parsed.data.artifacts_rest_resource !== resource)
+        throw authFailure(context, 'invalid_response', 'REST resource metadata must not advertise another artifacts_rest_resource', response.status);
+    const issuer = parsed.data.authorization_servers[0];
+    try {
+        endpoint(issuer);
+    }
+    catch {
+        throw authFailure(context, 'invalid_response', 'Invalid authorization server URL in protected resource metadata', response.status);
+    }
+    return { issuer, ...(parsed.data.artifacts_rest_resource === undefined ? {} : { restResource: parsed.data.artifacts_rest_resource }) };
+}
+function compatibleChallenge(value) {
+    if (!value)
+        return false;
+    const match = /^Bearer\s+(.+)$/i.exec(value);
+    if (!match)
+        return false;
+    const parameters = new Map();
+    const input = match[1];
+    const parameter = /\s*([!#$%&'*+.^_`|~0-9A-Za-z-]+)\s*=\s*(?:"((?:[^"\\]|\\[\x20-\x7e])*)"|([!#$%&'*+.^_`|~0-9A-Za-z-]+))\s*(,|$)/gy;
+    let position = 0;
+    while (position < input.length) {
+        parameter.lastIndex = position;
+        const param = parameter.exec(input);
+        if (!param || (param[4] === ',' && parameter.lastIndex === input.length))
+            return false;
+        const key = param[1].toLowerCase();
+        if (parameters.has(key))
+            return false;
+        parameters.set(key, param[2] === undefined ? param[3] : param[2].replace(/\\([\x20-\x7e])/g, '$1'));
+        position = parameter.lastIndex;
+    }
+    return parameters.get('error') === 'invalid_token' && (parameters.get('scope')?.split(/\s+/).includes('artifacts:read') ?? false);
+}
+async function checkIdentity(resource, request) {
+    const context = { phase: request.kind === 'anonymous' ? 'rest_preflight' : 'authenticated_identity', method: 'GET', url: `${restBase(resource)}/identity` };
+    const response = await boundedFetch(context, request.kind === 'anonymous' ? {} : { signal: request.signal, headers: { authorization: `Bearer ${request.accessToken}` } });
+    if (request.kind === 'anonymous') {
+        if (response.status === 401) {
+            const body = httpErrorSchema.safeParse(await jsonResponse(response, context));
+            if (body.success && body.data.error.code === 'unauthenticated' && compatibleChallenge(response.headers.get('www-authenticate')))
+                return;
+        }
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : 'REST identity route is incompatible. Use the exact REST URL or configure artifacts_rest_resource on the MCP server', response.status);
+    }
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : response.status === 401 || response.status === 403 ? 'access_denied' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : response.status === 401 || response.status === 403 ? 'OAuth grant cannot access this Artifacts server' : 'REST identity route is unavailable. Confirm the configured REST URL', response.status);
+    const parsed = identitySchema.safeParse(await jsonResponse(response, context));
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid REST identity response', response.status);
+    if (request.claims.sub !== parsed.data.userId || (request.claims.sid !== undefined && request.claims.sid !== parsed.data.sessionId))
+        throw authFailure(context, 'invalid_response', 'OAuth identity does not match the Artifacts session', response.status);
+    return parsed.data;
+}
+async function oauth(issuer, signal, operation) {
+    const observations = [];
+    try {
+        const result = await operation(discoveryOptions(issuer, signal, observations));
+        if (result instanceof oidc.Configuration) {
+            validateConfiguration(result, issuer, observations);
+            result[oidc.customFetch] = discoveryOptions(issuer, signal)[oidc.customFetch];
+        }
+        return result;
+    }
+    catch (error) {
+        let cause = error;
+        let observed;
+        for (let depth = 0; depth < 5; depth++) {
+            if (cause instanceof HttpError || cause instanceof AuthTransportError)
+                throw cause;
+            const response = cause instanceof Response ? cause : cause instanceof Error && 'response' in cause ? cause.response : undefined;
+            if (response instanceof Response)
+                observed = observations.find((item) => item.response === response);
+            if (observed || !(cause instanceof Error))
+                break;
+            cause = cause.cause;
+        }
+        observed ??= observations.at(-1);
+        if (observed)
+            throw authFailure(observed.context, 'invalid_response', 'OAuth protocol validation failed', observed.response.status);
+        throw new Error('OAuth protocol validation failed');
+    }
+}
+function discoveryOptions(issuer, signal, observations) {
     endpoint(issuer);
     return {
         timeout: networkTimeout / 1000,
         execute: [...(new URL(issuer).protocol === 'http:' ? [oidc.allowInsecureRequests] : []), oidc.enableNonRepudiationChecks],
-        [oidc.customFetch]: (url, options) => boundedFetch(endpoint(url, issuer), { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body }),
+        [oidc.customFetch]: async (url, options) => {
+            const context = { phase: 'oauth', method: options.method ?? 'GET', url };
+            try {
+                endpoint(url, issuer);
+            }
+            catch {
+                throw authFailure({ ...context, url: issuer }, 'invalid_response', 'Invalid OAuth endpoint');
+            }
+            const response = await boundedFetch(context, { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body });
+            if (!response.ok)
+                throw authFailure(context, response.status >= 500 ? 'service_error' : 'oauth_error', response.status >= 500 ? 'OAuth service failed' : 'OAuth request failed', response.status);
+            observations?.push({ context, response });
+            return response;
+        },
     };
 }
-function validateConfiguration(config, issuer) {
+function validateConfiguration(config, issuer, observations) {
+    const discovery = observations.find((item) => item.context.method === 'GET');
+    const registration = observations.find((item) => item.context.method === 'POST');
+    if (!discovery)
+        throw new Error('OAuth discovery response was not observed');
+    const failDiscovery = (message) => authFailure(discovery.context, 'invalid_response', message, discovery.response.status);
     const metadata = config.serverMetadata();
     if (metadata.issuer !== issuer)
-        throw new Error('OAuth issuer metadata does not match the configured issuer');
+        throw failDiscovery('OAuth issuer metadata does not match the configured issuer');
     for (const [key, value] of Object.entries(metadata)) {
-        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string')
-            endpoint(value, issuer);
+        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string') {
+            try {
+                endpoint(value, issuer);
+            }
+            catch (error) {
+                const message = error instanceof Error && error.message === 'OAuth endpoints must use the issuer origin' ? error.message : 'OAuth URLs require HTTPS or an exact loopback HTTP host, without credentials, query, or fragment';
+                throw failDiscovery(message);
+            }
+        }
     }
     if (!metadata.authorization_endpoint || !metadata.token_endpoint)
-        throw new Error('OAuth metadata is missing authorization or token endpoints');
-    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none')
-        throw new Error('The CLI requires a public OAuth client without a secret');
+        throw failDiscovery('OAuth metadata is missing authorization or token endpoints');
+    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none') {
+        const message = 'The CLI requires a public OAuth client without a secret';
+        throw registration ? authFailure(registration.context, 'invalid_response', message, registration.response.status) : new Error(message);
+    }
 }
 async function configuration(registration, signal) {
-    const config = await oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), discoveryOptions(registration.issuer, signal));
-    validateConfiguration(config, registration.issuer);
-    return config;
+    return oauth(registration.issuer, signal, (options) => oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), options));
 }
 function tokenRecord(tokens, previousRefresh) {
     if (typeof tokens.expires_in !== 'number' || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0)
@@ -142,7 +287,11 @@ async function openBrowser(url) {
     });
 }
 export async function login(options) {
-    const resource = canonicalResource(options.resource);
+    const source = canonicalResource(options.resource);
+    const metadata = await discoverResource(source);
+    const resource = metadata.restResource ?? source;
+    const { issuer } = resource === source ? metadata : await discoverResource(resource, true);
+    await checkIdentity(resource, { kind: 'anonymous' });
     const store = await CredentialStore.open(options.stateDir);
     let listener;
     try {
@@ -151,14 +300,6 @@ export async function login(options) {
             store.write(resource, { ...profile, epoch: profile.epoch + 1 });
             return profile.epoch + 1;
         });
-        const response = await boundedFetch(protectedResourceMetadataUrl(resource));
-        if (!response.ok)
-            throw new Error('Cannot discover the protected resource');
-        const metadata = resourceMetadata.parse(await response.json());
-        if (metadata.resource !== resource)
-            throw new Error('Protected resource metadata does not match the exact server URL');
-        const issuer = metadata.authorization_servers[0];
-        endpoint(issuer);
         listener = await callback();
         const { redirectUri, signal } = listener;
         const config = await store.exclusive(async () => {
@@ -167,11 +308,10 @@ export async function login(options) {
                 throw new Error('Login was superseded by another login or logout');
             if (profile.registration?.issuer === issuer)
                 return configuration(profile.registration, signal);
-            const registered = await oidc.dynamicClientRegistration(new URL(issuer), {
+            const registered = await oauth(issuer, signal, (options) => oidc.dynamicClientRegistration(new URL(issuer), {
                 client_name: 'Artifacts CLI', application_type: 'native', token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA',
                 redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], scope: scopes,
-            }, oidc.None(), discoveryOptions(issuer, signal));
-            validateConfiguration(registered, issuer);
+            }, oidc.None(), options));
             store.write(resource, { ...profile, registration: { issuer, clientId: registered.clientMetadata().client_id }, tokens: null, refreshAttempt: null });
             return registered;
         });
@@ -187,22 +327,21 @@ export async function login(options) {
         if (!options.noBrowser)
             await openBrowser(authorizationUrl);
         const currentUrl = await authorization;
+        if (currentUrl.searchParams.has('error'))
+            throw new Error(currentUrl.searchParams.get('error') === 'access_denied' ? 'Authorization denied' : 'Authorization failed');
         return await store.exclusive(async () => {
             const profile = store.read(resource);
             if (profile.epoch !== epoch)
                 throw new Error('Login was superseded by another login or logout');
-            const tokens = await oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            const tokens = await oauth(issuer, signal, (options) => {
+                config[oidc.customFetch] = options[oidc.customFetch];
+                return oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            });
             const credentials = tokenRecord(tokens);
-            const identityResponse = await boundedFetch(`${restBase(resource)}/identity`, { signal, headers: { authorization: `Bearer ${credentials.accessToken}` } });
-            if (!identityResponse.ok)
-                throw new Error('The OAuth grant cannot access this Artifacts server');
-            const identity = identitySchema.parse(await identityResponse.json());
-            const claims = tokens.claims();
-            if (claims.sub !== identity.userId || (claims.sid !== undefined && claims.sid !== identity.sessionId))
-                throw new Error('OAuth identity does not match the Artifacts session');
+            const identity = await checkIdentity(resource, { kind: 'authenticated', accessToken: credentials.accessToken, signal, claims: tokens.claims() });
             signal.throwIfAborted();
-            store.write(resource, { ...profile, tokens: credentials, refreshAttempt: null });
-            return identity;
+            store.commitLogin(resource, epoch, credentials);
+            return { resource, identity };
         });
     }
     finally {

package/src/credentials.d.ts

@@ -32,6 +32,8 @@ export declare class CredentialStore {
     exclusive<T>(work: () => T | Promise<T>): Promise<T>;
     read(resource: string): CredentialProfile;
     write(resource: string, profile: CredentialProfile): void;
+    readSelectedResource(): string | undefined;
+    commitLogin(resource: string, epoch: number, tokens: Tokens): void;
     close(): void;
 }
 export {};

package/src/credentials.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { setTimeout as delay } from 'node:timers/promises';
 import { z } from 'zod';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const registrationSchema = z.strictObject({ issuer: z.string(), clientId: z.string().min(1) });
 const tokensSchema = z.strictObject({ accessToken: z.string().min(1), refreshToken: z.string().min(1).optional(), expiresAt: z.number().finite() });
 const profileSchema = z.strictObject({
@@ -50,6 +51,7 @@ export class CredentialStore {
             await store.exclusive(() => {
                 data.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;');
                 data.exec('CREATE TABLE IF NOT EXISTS profiles (resource TEXT PRIMARY KEY, profile TEXT NOT NULL) STRICT');
+                data.exec('CREATE TABLE IF NOT EXISTS selected_resource (id INTEGER PRIMARY KEY CHECK (id = 1), resource TEXT NOT NULL) STRICT');
             });
             return store;
         }
@@ -90,5 +92,25 @@ export class CredentialStore {
     write(resource, profile) {
         this.data.prepare('INSERT INTO profiles(resource, profile) VALUES (?, ?) ON CONFLICT(resource) DO UPDATE SET profile = excluded.profile').run(resource, JSON.stringify(profileSchema.parse(profile)));
     }
+    readSelectedResource() {
+        const row = this.data.prepare('SELECT resource FROM selected_resource WHERE id = 1').get();
+        return row ? canonicalResource(String(row.resource)) : undefined;
+    }
+    commitLogin(resource, epoch, tokens) {
+        canonicalResource(resource);
+        this.data.exec('BEGIN IMMEDIATE');
+        try {
+            const profile = this.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            this.write(resource, { ...profile, tokens, refreshAttempt: null });
+            this.data.prepare('INSERT INTO selected_resource(id, resource) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET resource = excluded.resource').run(resource);
+            this.data.exec('COMMIT');
+        }
+        catch (error) {
+            this.data.exec('ROLLBACK');
+            throw error;
+        }
+    }
     close() { this.data.close(); this.lock.close(); }
 }

package/src/index.js

@@ -10,12 +10,14 @@ import { createSchema, listSharesSchema, moveSchema, publishSchema, shareSchema,
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
+import { CredentialStore } from "./credentials.js";
 import { loadOperation, retainOperation, submitOperation } from "./operations.js";
 import { runSkillsCommand } from "./skills.js";
 const help = `Usage: artifacts COMMAND [OPTIONS]
 
 Global options:
-  --server RESOURCE       Canonical OAuth resource, or ARTIFACTS_SERVER
+  --server RESOURCE       Exact REST OAuth resource, or ARTIFACTS_SERVER
+                         Defaults to the last successful login
   --state-dir DIR         Private local state, or ARTIFACTS_STATE_DIR
                          Default: ~/.local/state/artifacts
   --help                 Print this reference
@@ -30,12 +32,14 @@ Commands:
   login [--no-browser]
   logout
   whoami
-  create --snapshot FILE [--project NAME] [--request-id ID]
+  create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
          [--response full|compact]
   create --command FILE
   list [--limit N] [--cursor CURSOR] [--project NAME]
   projects
   read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+  read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+         [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
   update [ID] --command FILE
@@ -57,10 +61,23 @@ submission. Retry sends the exact retained command for the same server and owner
 Projects group artifacts by name without regard to letter case. A project
 exists while it contains an artifact. Move changes the project of an artifact
 without creating a revision; --no-project removes it from its project.
+A slug such as concepts/rag names an artifact within its project, or within
+the unfiled artifacts without --project. Read --slug finds it without its ID.
 Read --out saves the returned artifact JSON. Export --out saves the ZIP.
 Read --quiet requires --out and suppresses successful JSON stdout.
 Output files are created exclusively and never overwrite an existing path.
 JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+Login accepts an MCP URL when its metadata advertises artifacts_rest_resource.
+Split MCP and REST resources require this relation. Login remembers the verified
+REST URL for later commands. --server takes precedence over ARTIFACTS_SERVER,
+which takes precedence over the saved URL. Ordinary overrides do not replace
+the saved URL. Logout keeps it for a later login.
+Login checks <resource>/v1/identity before browser
+authorization. Legacy /mcp
+resources work when their REST API is at /mcp/v1. If the check fails, confirm
+the configured REST URL with your service administrator.
+Login errors report the phase, method, endpoint, and HTTP status when received.
+Network failures have no HTTP status. Login verifies identity again after OAuth.
 ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
 Skills commands work offline without a server, login, or private state.
 They print plain text. Global server and state options are accepted and ignored.
@@ -73,8 +90,8 @@ class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
-    create: ['snapshot', 'project', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor', 'project'], projects: [], read: ['revision', 'response', 'out', 'quiet'],
+    create: ['snapshot', 'project', 'slug', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], read: ['slug', 'project', 'revision', 'response', 'out', 'quiet'],
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
@@ -116,7 +133,7 @@ async function main() {
             summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
             full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
             global: { type: 'boolean' }, force: { type: 'boolean' },
-            project: { type: 'string' }, 'no-project': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, slug: { type: 'string' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -144,11 +161,20 @@ async function main() {
             throw new UsageError(`Option --${option} is not supported by ${command}`);
     if (command === 'skills')
         return runSkillsCommand(arguments_, values, seen);
-    const resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
-    if (!resourceValue)
-        throw new UsageError('Specify --server RESOURCE or ARTIFACTS_SERVER. No production server is selected by default.');
-    const resource = canonicalResource(resourceValue);
     const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    let resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (resourceValue === undefined) {
+        const store = await CredentialStore.open(stateDir);
+        try {
+            resourceValue = await store.exclusive(() => store.readSelectedResource());
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (resourceValue === undefined)
+        throw new UsageError('No server is saved. Run artifacts login --server RESOURCE or set ARTIFACTS_SERVER.');
+    const resource = canonicalResource(resourceValue);
     function argument(required = true) {
         if (arguments_.length > 1 || (required && arguments_.length !== 1))
             throw new UsageError(`${command} requires ${required ? 'one' : 'zero or one'} positional argument`);
@@ -204,7 +230,12 @@ async function main() {
     switch (command) {
         case 'login':
             none();
-            return login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+            {
+                const result = await login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+                if (result.resource !== resource)
+                    process.stderr.write(`REST resource: ${result.resource}\nThis verified REST URL is saved for subsequent commands.\n`);
+                return result.identity;
+            }
         case 'logout':
             none();
             return logout({ resource, stateDir });
@@ -215,7 +246,7 @@ async function main() {
             if (values.command)
                 return mutate(await commandFile('create'));
             none();
-            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(response === undefined ? {} : { response }) }) });
+            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(values.slug === undefined ? {} : { slug: values.slug }), ...(response === undefined ? {} : { response }) }) });
         }
         case 'list':
             none();
@@ -224,7 +255,12 @@ async function main() {
             none();
             return client.projects();
         case 'read': {
-            const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.slug === undefined && values.project !== undefined)
+                throw new UsageError('read --project requires --slug');
+            if ((values.slug === undefined) !== (arguments_.length === 1) || arguments_.length > 1)
+                throw new UsageError('read requires exactly one of an artifact ID or --slug SLUG');
+            const target = values.slug === undefined ? { artifactId: arguments_[0] } : { slug: values.slug, ...(values.project === undefined ? {} : { project: values.project }) };
+            const result = await client.read({ ...target, ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
                 await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
             return quiet ? undefined : result;

package/src/operations.d.ts

@@ -31,6 +31,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
         project: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
         response: z.ZodOptional<z.ZodEnum<{
             full: "full";
             compact: "compact";