[codex] publish agent skills discovery index (#139)

* add agent skills discovery index

* address agent skills review comments

Author: basit3407

.gitattributes

@@ -0,0 +1 @@
+static/.well-known/agent-skills/** text eol=lf

static/.well-known/agent-skills/index.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "skills": [
+    {
+      "name": "quran-foundation-api-docs",
+      "type": "skill-md",
+      "description": "Use Quran Foundation docs and tutorials to choose the correct API family, authentication flow, endpoint, font rendering approach, request-access prerequisite, and official references for content, search, OAuth2/OIDC, user-related, and Quran Reflect integrations.",
+      "url": "/.well-known/agent-skills/quran-foundation-api-docs/SKILL.md",
+      "digest": "sha256:df258de3417829586f3ccbd6176558df239d89240396719ceba7c2f5388d9253"
+    }
+  ]
+}

static/.well-known/agent-skills/quran-foundation-api-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: quran-foundation-api-docs
+description: Use Quran Foundation docs and tutorials to choose the correct API family, authentication flow, endpoint, font rendering approach, request-access prerequisite, and official references for content, search, OAuth2/OIDC, user-related, and Quran Reflect integrations.
+---
+
+# Quran Foundation API Docs
+
+## Use When
+
+- The task involves Quran Foundation APIs, api-docs.quran.foundation, Quran.com integrations, or quranreflect.com integrations.
+- The user needs official endpoint selection, request or response details, auth guidance, scopes, quickstarts, or migration help.
+- The user needs font rendering or Mushaf page-layout guidance.
+- The user needs OAuth2 or OIDC setup guidance across web or mobile platforms.
+- The user needs onboarding details such as client provisioning or Request Access.
+- The task involves Quran Reflect or quranreflect.com features backed by Quran Foundation APIs.
+- The user wants links to official documentation or OpenAPI specifications.
+
+## Do Not Use When
+
+- The task is unrelated to Quran Foundation APIs.
+- The user needs live production data, account-specific secrets, or environment access that is not present in the docs.
+
+## Route The Request First
+
+1. Identify the correct API family.
+   - Content APIs v4: Quran text, translations, tafsir, audio, recitations, verses, chapters, pages, juz, hizb, ruku, manzil, and related content.
+   - Search APIs v1: Quran search queries and search-related integration.
+   - OAuth2 APIs v1 and OIDC docs: authentication, authorization, tokens, discovery, and login flows.
+   - User-related APIs v1: bookmarks, collections, notes, profiles, reading sessions, rooms, posts, and related user features.
+   - Font and page-layout tutorials: script rendering, Mushaf layouts, and page-based display guidance.
+   - Quran Reflect integrations: posts, comments, feeds, likes, saves, room/page/community features, and related scopes.
+2. Prefer stable production docs by default.
+3. Only use pre-live user-related docs when the user explicitly asks for upcoming or unreleased behavior.
+
+## Canonical Sources
+
+- Docs home: `https://api-docs.quran.foundation/`
+- Content OpenAPI: `https://api-docs.quran.foundation/openAPI/content/v4.json`
+- Search OpenAPI: `https://api-docs.quran.foundation/openAPI/search/v1.json`
+- OAuth2 OpenAPI: `https://api-docs.quran.foundation/openAPI/oauth2-apis/v1.json`
+- User-related OpenAPI (production): `https://api-docs.quran.foundation/openAPI/user-related-apis/v1.json`
+- User-related OpenAPI (pre-live): `https://api-docs.quran.foundation/openAPI/user-related-apis/pre-live/v1.json`
+- User APIs OIDC quickstart: `https://api-docs.quran.foundation/docs/tutorials/oidc/user-apis-quickstart/`
+- OAuth2 getting started: `https://api-docs.quran.foundation/docs/tutorials/oidc/getting-started-with-oauth2/`
+- OpenID Connect tutorial: `https://api-docs.quran.foundation/docs/tutorials/oidc/openid-connect/`
+- OIDC client setup: `https://api-docs.quran.foundation/docs/tutorials/oidc/client-setup/`
+- OAuth2 web integration example: `https://api-docs.quran.foundation/docs/tutorials/oidc/example-integration/`
+- Mobile apps overview: `https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/`
+- Android mobile OIDC guide: `https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/android/`
+- iOS mobile OIDC guide: `https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/iOS/`
+- React Native OIDC guide: `https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/react-native/`
+- Content API quickstart: `https://api-docs.quran.foundation/docs/quickstart/`
+- Font rendering tutorial: `https://api-docs.quran.foundation/docs/tutorials/fonts/font-rendering/`
+- Page layout tutorial: `https://api-docs.quran.foundation/docs/tutorials/fonts/page-layout/`
+- Request access: `https://api-docs.quran.foundation/request-access/`
+- FAQ: `https://api-docs.quran.foundation/docs/tutorials/faq/`
+- API catalog: `https://api-docs.quran.foundation/.well-known/api-catalog`
+
+## Working Rules
+
+- Cite official Quran Foundation docs or OpenAPI specs when giving implementation guidance.
+- Prefer the most specific doc page for the endpoint in question, not just the docs home page.
+- Do not invent endpoints, scopes, parameters, headers, or response fields. Confirm them from the docs or OpenAPI.
+- Distinguish documentation URLs from API base URLs.
+- For auth questions, call out whether the answer belongs to OAuth2/OIDC or to an application API.
+- For setup questions, mention if Request Access and registered redirect URIs are prerequisites.
+- For Quran font questions, choose between Unicode text rendering and page-based glyph rendering based on the user's display requirements.
+- For Quran Reflect-related questions, check post, comment, feed, room, and scope docs before answering.
+- If multiple endpoints could fit, explain the best match and mention the alternative only if it materially changes implementation.
+- If the user asks for sample code, keep it aligned with documented auth and base URL expectations.
+
+## Fast Routing Hints
+
+- "Get verses, translations, tafsir, chapters, audio, or recitations" -> Content APIs v4
+- "Search the Quran" -> Search APIs v1
+- "Login, tokens, discovery, issuer metadata, OAuth2, OIDC" -> OAuth2 APIs v1 plus OIDC docs
+- "Bookmarks, collections, notes, reading sessions, profile, rooms, posts" -> User-related APIs v1
+- "Web login flow, PKCE, callback, mobile auth, redirect URIs" -> OIDC tutorial pages plus OAuth2 APIs
+- "Fonts, glyph codes, Mushaf pages, script rendering, Tajweed display" -> Font rendering and page-layout tutorials plus relevant content endpoints
+- "Quran Reflect feed, post, comment, like, save, room, or community behavior" -> User-related posts and rooms docs, and content feed/read docs where applicable
+- "Upcoming user API behavior" -> Pre-live user-related docs, and clearly label them as pre-live
+
+## Expected Output
+
+- Name the API family first.
+- Link the exact doc page or OpenAPI spec used.
+- State any auth requirement or prerequisite clearly.
+- If relevant, mention whether the guidance is production or pre-live.

tests/agent-skills-discovery-index.test.cjs

@@ -0,0 +1,70 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const indexPath = path.join(
+  __dirname,
+  '..',
+  'static',
+  '.well-known',
+  'agent-skills',
+  'index.json',
+);
+const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+
+test('publishes an Agent Skills discovery index with the v0.2.0 schema', () => {
+  assert.equal(
+    index.$schema,
+    'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+  );
+  assert.ok(Array.isArray(index.skills));
+  assert.ok(index.skills.length > 0);
+});
+
+test('validates required RFC v0.2.0 skill entry fields', () => {
+  for (const skill of index.skills) {
+    assert.equal(typeof skill.name, 'string');
+    assert.match(skill.name, /^(?!-)(?!.*--)[a-z0-9-]{1,64}(?<!-)$/);
+
+    assert.ok(['skill-md', 'archive'].includes(skill.type));
+
+    assert.equal(typeof skill.description, 'string');
+    assert.ok(skill.description.length > 0);
+    assert.ok(skill.description.length <= 1024);
+
+    assert.equal(typeof skill.url, 'string');
+    assert.ok(skill.url.length > 0);
+
+    assert.equal(typeof skill.digest, 'string');
+    assert.match(skill.digest, /^sha256:[0-9a-f]{64}$/);
+  }
+});
+
+test('matches each published skill-md digest to the raw SKILL.md bytes', () => {
+  for (const skill of index.skills) {
+    if (skill.type !== 'skill-md') {
+      continue;
+    }
+
+    assert.match(
+      skill.url,
+      /^\/\.well-known\/agent-skills\/[a-z0-9-]+\/SKILL\.md$/,
+    );
+
+    const localSkillPath = path.join(
+      __dirname,
+      '..',
+      'static',
+      ...skill.url.replace(/^\//, '').split('/'),
+    );
+    const rawBytes = fs.readFileSync(localSkillPath);
+    const digest = `sha256:${crypto
+      .createHash('sha256')
+      .update(rawBytes)
+      .digest('hex')}`;
+
+    assert.equal(skill.digest, digest);
+  }
+});