@nshipster/sosumi 1.0.0 → 1.0.4

package/README.md

@@ -2,38 +2,42 @@
 
 Making Apple docs AI-readable.
 
-[sosumi.ai](https://sosumi.ai) 
-provides Apple Developer documentation in an AI-readable format 
+[sosumi.ai](https://sosumi.ai)
+provides Apple Developer documentation in an AI-readable format
 by converting JavaScript-rendered pages into Markdown.
 
 ## Usage
 
 ### HTTP API
 
-Replace `developer.apple.com` with `sosumi.ai` 
+Replace `developer.apple.com` with `sosumi.ai`
 in any Apple Developer documentation URL:
 
 **Original:**
+
 ```
 https://developer.apple.com/documentation/swift/array
 ```
 
 **AI-readable:**
+
 ```
 https://sosumi.ai/documentation/swift/array
 ```
 
-This works for all API reference docs, 
+This works for all API reference docs,
 as well as Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) (HIG).
 
 WWDC session transcripts are also supported by replacing the same host for video URLs:
 
 **Original:**
+
 ```
 https://developer.apple.com/videos/play/wwdc2021/10133/
 ```
 
 **AI-readable:**
+
 ```
 https://sosumi.ai/videos/play/wwdc2021/10133
 ```
@@ -41,11 +45,13 @@ https://sosumi.ai/videos/play/wwdc2021/10133
 Sosumi can also proxy public non-Apple Swift-DocC pages using:
 
 **Original:**
+
 ```
 https://apple.github.io/swift-argument-parser/documentation/argumentparser
 ```
 
 **AI-readable:**
+
 ```
 https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser
 ```
@@ -60,8 +66,8 @@ https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documen
 
 ### MCP Integration
 
-Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport. 
-If your client supports either of these, 
+Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport.
+If your client supports either of these,
 configure it to connect directly to `https://sosumi.ai/mcp`.
 
 Otherwise,
@@ -148,11 +154,23 @@ sosumi fetch https://developer.apple.com/documentation/swift/array --json
 sosumi search "SwiftData" --json
 ```
 
+### AI Agent Skill
+
+Want your AI coding assistant to use Sosumi consistently?
+Use the hosted skill file:
+[`https://sosumi.ai/SKILL.md`](https://sosumi.ai/SKILL.md)
+
+Spec-compliant clients can also install it with:
+
+```bash
+npx skills add https://sosumi.ai
+```
+
 ### Chrome Extension
 
-You can also use Sosumi from a community-contributed 
+You can also use Sosumi from a community-contributed
 [Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj?utm_source=item-share-cb),
-which adds a "Copy sosumi Link" button 
+which adds a "Copy sosumi Link" button
 to Apple Developer documentation pages.
 [Source code](https://github.com/FromAtom/Link-Generator-for-sosumi.ai) is available on GitHub.
 
@@ -161,11 +179,11 @@ to Apple Developer documentation pages.
 This project is designed to be easily run on your own machine
 or deployed to a hosting provider.
 
-Sosumi.ai is currently hosted by 
+Sosumi.ai is currently hosted by
 [Cloudflare Workers](https://workers.cloudflare.com).
 
 > [!NOTE]  
-> The application is built with Hono, 
+> The application is built with Hono,
 > making it compatible with various runtimes.
 >
 > See the [Hono docs](https://hono.dev/docs/getting-started/basic)
@@ -173,23 +191,26 @@ Sosumi.ai is currently hosted by
 
 ### Prerequisites
 
-- Node.js 18+
+- Node.js 20+
 - npm
 
 ### Quick Start
 
 1. **Clone the repository:**
+
    ```bash
    git clone https://github.com/nshipster/sosumi.ai.git
    cd sosumi.ai
    ```
 
 2. **Install dependencies:**
+
    ```bash
    npm install
    ```
 
 3. **Start development server:**
+
    ```bash
    npm run dev
    ```
@@ -197,7 +218,7 @@ Sosumi.ai is currently hosted by
 Once the application is up and running, press the <kbd>b</kbd>
 to open the URL in your browser.
 
-To configure MCP clients to use your development server, 
+To configure MCP clients to use your development server,
 replace `sosumi.ai` with the local server address
 (`http://localhost:8787` by default).
 
@@ -227,7 +248,7 @@ npm run test:run      # Run tests once
 ```
 
 > [!TIP]
-> When running the CLI through npm scripts during local development, 
+> When running the CLI through npm scripts during local development,
 > use `-s` (`--silent`)
 > to suppress npm's script preamble so output pipes cleanly:
 >
@@ -237,7 +258,7 @@ npm run test:run      # Run tests once
 
 ### Code Quality
 
-This project uses [Biome](https://biomejs.dev/) 
+This project uses [Biome](https://biomejs.dev/)
 for code formatting, linting, and import organization.
 
 - `npm run format` - Format all code files
@@ -255,7 +276,7 @@ For the best development experience, install the Biome extension for your editor
 
 ### Cloudflare Workers
 
-Whenever you update your `wrangler.toml` or change your Worker bindings, 
+Whenever you update your `wrangler.toml` or change your Worker bindings,
 be sure to re-run:
 
 ```bash

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@nshipster/sosumi",
-  "version": "1.0.0",
+  "version": "1.0.4",
+  "description": "Making Apple docs AI-readable",
   "license": "MIT",
+  "author": "NSHipster",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NSHipster/sosumi.ai"
+  },
+  "keywords": [
+    "apple",
+    "docs",
+    "documentation",
+    "mcp",
+    "cli",
+    "markdown",
+    "swift-docc",
+    "ai"
+  ],
+  "preferGlobal": true,
+  "homepage": "https://sosumi.ai",
+  "bugs": {
+    "url": "https://github.com/NSHipster/sosumi.ai/issues"
+  },
   "type": "module",
   "engines": {
     "node": ">=20.18.1"
@@ -18,7 +39,7 @@
     "access": "public"
   },
   "bin": {
-    "sosumi": "./bin/sosumi.mjs"
+    "sosumi": "bin/sosumi.mjs"
   },
   "scripts": {
     "dev": "wrangler dev",
@@ -45,7 +66,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.2.2",
     "@cloudflare/puppeteer": "^1.0.4",
-    "@cloudflare/vitest-pool-workers": "^0.8.68",
+    "@cloudflare/vitest-pool-workers": "^0.12.18",
     "@vitest/ui": "^3.2.4",
     "vitest": "^3.2.4",
     "wrangler": "^4.32.0"

package/public/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: sosumi
+description: Fetches Apple documentation as Markdown via Sosumi. Use for Apple API reference, Human Interface Guidelines, WWDC transcripts, and external Swift-DocC pages.
+---
+
+# Sosumi Skill
+
+Use this skill to reliably fetch Apple docs as Markdown when coding agents need precise API details.
+
+## When to Use
+
+Use Sosumi when the request involves any of the following:
+
+- Apple platform APIs (`Swift`, `SwiftUI`, `UIKit`, `AppKit`, `Foundation`, etc.)
+- API signatures, availability, parameter behavior, or return semantics
+- Human Interface Guidelines questions
+- WWDC session transcript lookup
+- External Swift-DocC documentation (for example, GitHub Pages or Swift Package Index hosts)
+
+## Core Workflow
+
+1. If you already have a `developer.apple.com` URL, replace the host with `sosumi.ai` and keep the same path.
+2. If you do not know the exact page path, search first, then fetch the best match.
+3. Prefer specific symbol pages instead of broad top-level pages when answering implementation questions.
+
+### Optional CLI Preflight
+
+If the Sosumi CLI is available, quickly verify local access before deeper debugging:
+
+- `sosumi --version` confirms the CLI is installed and on `PATH`.
+- `sosumi --help` shows top-level usage.
+- `sosumi <command> --help` is the manual for command-specific behavior.
+
+## HTTP Usage
+
+Replace `developer.apple.com` with `sosumi.ai`:
+
+- Original: `https://developer.apple.com/documentation/swift/array`
+- AI-readable: `https://sosumi.ai/documentation/swift/array`
+
+## Content Types
+
+### Apple API Reference
+
+- Pattern: `https://sosumi.ai/documentation/{framework}/{symbol}`
+- Examples:
+  - `https://sosumi.ai/documentation/swift/array`
+  - `https://sosumi.ai/documentation/swiftui/view`
+
+### Human Interface Guidelines
+
+- Pattern: `https://sosumi.ai/design/human-interface-guidelines/{topic}`
+- Examples:
+  - `https://sosumi.ai/design/human-interface-guidelines`
+  - `https://sosumi.ai/design/human-interface-guidelines/foundations/color`
+
+### Apple Video Transcripts
+
+- Pattern: `https://sosumi.ai/videos/play/{collection}/{id}`
+- Examples:
+  - `https://sosumi.ai/videos/play/wwdc2021/10133`
+  - `https://sosumi.ai/videos/play/meet-with-apple/208`
+
+### External Swift-DocC
+
+- Pattern: `https://sosumi.ai/external/{full-https-url}`
+- Examples:
+  - `https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser/`
+  - `https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/1.23.1/documentation/composablearchitecture`
+
+## MCP Tools Quick Reference
+
+Use these when Sosumi is configured as an MCP server (`https://sosumi.ai/mcp`):
+
+| Tool | Parameters | Use |
+|---|---|---|
+| `searchAppleDocumentation` | `query: string` | Search Apple documentation and return structured results |
+| `fetchAppleDocumentation` | `path: string` | Fetch Apple docs or HIG content by path as Markdown |
+| `fetchAppleVideoTranscript` | `path: string` | Fetch Apple video transcript by `/videos/play/...` path |
+| `fetchExternalDocumentation` | `url: string` | Fetch external Swift-DocC page by absolute HTTPS URL |
+
+## Best Practices
+
+- Search first if the exact path is unknown.
+- Fetch targeted symbol pages for coding questions.
+- Keep source links in answers so users can verify details quickly.
+- Use Sosumi paths directly in responses whenever referencing Apple documentation pages.
+
+## Troubleshooting
+
+### 404 or sparse output
+
+- The path may be incorrect or too broad.
+- Run a search query first, then fetch a specific result path.
+
+### External page cannot be fetched
+
+- The host may block access via `robots.txt` or `X-Robots-Tag` directives.
+- Try another canonical page URL for the same symbol.