docs: document ChatGPT MCP OAuth

README.md

@@ -35,7 +35,7 @@ codex plugin add shd-mcp-plugin@shd-public
 The same commands work with the Gitea clone URL:
 
 ```bash
-git clone https://git.xyz.su/shd/shd-mcp-plugin.git
+git clone https://git.xyz.su/markkats/shd-mcp-plugin.git
 ```
 
 After installation, start a new Codex thread so the plugin Skills are loaded.
@@ -62,6 +62,18 @@ The backend serves the checked-in widget artifact at
 `ui://shd/active-projects/v1.html`; its manifest and `SHA256SUMS` are kept next
 to the HTML resource under `plugins/shd-mcp-plugin/widgets/active-projects/v1/`.
 
+The same read-only data/render contract is available for Documents, Tasks,
+Finance and CRM:
+
+- `shd_render_documents_widget` → `ui://shd/documents/v1.html`;
+- `shd_render_tasks_widget` → `ui://shd/tasks/v1.html`;
+- `shd_render_finance_widget` → `ui://shd/finance/v1.html`;
+- `shd_render_crm_widget` → `ui://shd/crm/v1.html`.
+
+Each widget accepts normalized records from its list tool, keeps the plain
+structured response as a fallback and uses the MCP Apps bridge before the
+`window.openai` compatibility API.
+
 The official OpenAI directory is optional. It is useful for public discovery,
 one-click installation and review of a public app; it is not required for an
 internal team or a manually added ChatGPT custom app. See the official
@@ -85,6 +97,11 @@ token may be used only if the selected MCP client and SHD deployment
 explicitly support it; enter it in that client's secure connection settings,
 never in `.mcp.json`, Skills or an issue.
 
+SHD OAuth supports ChatGPT CIMD clients with PKCE S256 and
+`private_key_jwt` client authentication. The server validates the client
+assertion against ChatGPT's published JWKS; the plugin package never stores
+the assertion, access token or refresh token.
+
 For ChatGPT or another MCP client without Codex plugin installation, add the
 same HTTPS endpoint as a custom MCP app and complete OAuth there. The public
 repository packages the workflows; it does not grant access to the server.
@@ -109,9 +126,44 @@ From the repository root:
 
 ```bash
 python3 -m unittest discover -s tests -v
-sha256sum --check plugins/shd-mcp-plugin/widgets/active-projects/v1/SHA256SUMS
+python3 scripts/check_skill_mcp_parity.py --strict
+for checksum in plugins/shd-mcp-plugin/widgets/*/v1/SHA256SUMS; do
+  (cd "$(dirname "$checksum")" && sha256sum --check SHA256SUMS)
+done
 ```
 
+Refresh the catalog snapshot after a backend MCP catalog change:
+
+```bash
+node /var/www/admin/scripts/mcp/mcp-catalog.mjs | \
+  python3 scripts/update_mcp_tool_catalog.py
+```
+
+The runtime smoke harness checks OAuth metadata, PKCE S256 support, the
+authenticated MCP handshake and all five widget resources. It never assumes
+an endpoint or prints a token:
+
+```bash
+SHD_MCP_RUNTIME_URL=https://approved-host.example/mcp \
+SHD_MCP_ACCESS_TOKEN="$TOKEN" \
+node scripts/mcp-runtime-smoke.mjs --require-auth
+```
+
+For a full authorization-code/PKCE browser check, provide an already
+authenticated Playwright storage state and the client redirect registered with
+SHD:
+
+```bash
+SHD_MCP_RUNTIME_URL=https://approved-host.example/mcp \
+SHD_OAUTH_E2E_STORAGE_STATE=/secure/oauth-state.json \
+SHD_OAUTH_E2E_CLIENT_ID="$OAUTH_CLIENT_ID" \
+SHD_OAUTH_E2E_REDIRECT_URI="$OAUTH_REDIRECT_URI" \
+node scripts/mcp-oauth-e2e.mjs
+```
+
+The browser/OAuth checks are opt-in deployment checks and are not run in the
+public static-package workflow.
+
 The full release boundary, including backend deployment and authenticated
 ChatGPT/browser checks, is documented in [RELEASE.md](RELEASE.md).