@sylphx/lookout 0.1.0 → 0.1.2

package/README.md

@@ -95,7 +95,7 @@ const extracted = await lookout.extract({ url: 'https://example.com' })
 | `web_search` | Public adapters (DuckDuckGo HTML + Wikipedia + npm registry + HN Algolia), rank fusion, query-term boost, host filters |
 | `web_fetch` | SSRF-safe HTTP(S) fetch, redirects, size limits, cite spans |
 | `web_extract` | Title, description, JSON-LD, tables, spans from HTML/URL |
-| `web_cache` | Local disk cache query/stats/clear/prune (`LOOKOUT_CACHE_DIR`, optional max age) |
+| `web_cache` (advanced) | Local disk cache query/stats/clear/prune (`LOOKOUT_CACHE_DIR`, optional max age) |
 | `web_crawl` *(advanced)* | Same-origin, depth-limited crawl (not a full-site crawler) |
 | `web_research` *(advanced)* | Search then fetch/extract top pages with citeable excerpts |
 

package/docs/BRAND_PUBLISH.md

@@ -1,36 +1,11 @@
-# Lookout — brand npm publish readiness
+# Lookout — brand npm publish
 
-**Publish authority:** this repository only (not a multi-product monorepo).
+**Publish authority:** this repository only.
 
 | Field | Value |
 | --- | --- |
 | Brand | **Lookout** |
-| Transitional npm id | `@sylphx/lookout` |
-| Target brand npm id | `@sylphx/lookout` |
-| Brand bin | `lookout` |
-| Marketplace title | Lookout (`server.json`) |
+| Canonical npm id | `@sylphx/lookout` |
+| Transitional id | _(none — shipped as brand from day one)_ |
 
-## Current policy
-
-1. Ship/publish `@sylphx/lookout` from this repo (existing CI/release train).
-2. Optional second publish of `@sylphx/lookout` **from this same repo** (same artifacts, renamed package.json at pack time).
-3. Never publish brand packages from any other repository.
-
-## Dry-run (no npm auth required)
-
-```bash
-# Transitional package as configured
-npm pack --dry-run
-# Or product-specific brand pack plan script when present:
-# bun scripts/brand-pack-plan.ts
-```
-
-## Blockers for live brand publish
-
-- npm automation token / 2FA for `@sylphx` scope
-- Changeset/version alignment with transitional package
-- Registry readback proof after publish
-
-## Authority
-
-Publish and brand packages only from **this repository**. No central Instruments monorepo.
+No dual-name expand required.

package/docs/LOCAL_FIRST_FRONTIER.md

@@ -0,0 +1,19 @@
+# Local-first frontier
+
+## Principles
+
+1. **Less dependency** — prefer OS/Rust binaries over heavy npm ML  
+2. **Zero config** — works without API keys  
+3. **Local first, cloud optional**  
+4. **Speed / size / performance**  
+5. **Rust first** where engines exist  
+
+See product README + EVIDENCE_CONTRACT for surfaces.
+
+## Non-negotiable
+
+1. Zero API key for default path  
+2. Prefer Rust native MCP when present  
+3. Few tools; primary path documented in TOOL_SURFACE.md  
+4. Cloud / LLM only optional and non-authority  
+5. Product SSOT is this repository only (no instruments monorepo)

package/docs/POSITIONING.md

@@ -21,7 +21,7 @@ Tiny default: public search adapters + fetch/extract/cache with citeable excerpt
 - `web_search`
 - `web_fetch`
 - `web_extract`
-- `web_cache`
+- ~~core~~ `web_cache` (advanced)
 - `web_crawl (advanced)`
 - `web_research (advanced)`
 

package/docs/PUBLISH.md

@@ -2,22 +2,19 @@
 
 | Field | Value |
 | --- | --- |
-| Package | `@sylphx/lookout` |
-| Repo version | `0.1.0` |
-| Registry state | **not on npm (404)** |
-| npm auth in this environment | `ENEEDAUTH` (external credential blocker) |
+| Transitional npm | `@sylphx/lookout` |
+| Brand npm | `— (canonical)` |
+| Version | `0.1.1` |
+| Registry | **live** (dual expand–contract where brand ≠ transitional) |
+| Auth | GitHub org `NPM_TOKEN` via publish workflows |
 
-## In-repo readiness
-
-- CI/tests/release-gate green on tip
-- `npm pack --dry-run` produces a valid TS package (~23KB)
-- Live `npm publish` blocked only by missing `@sylphx` registry auth in this environment
-
-## Install until publish lands
+## Install
 
 ```bash
-git clone https://github.com/SylphxAI/lookout.git
-cd lookout
-bun install
-./bin/lookout doctor
+# preferred brand
+npm i -g @sylphx/lookout
+# transitional still valid during expand
+npm i -g @sylphx/lookout
 ```
+
+Workflows: `publish-npm-package.yml`, `publish-brand-alias.yml`.

package/docs/TOOL_SURFACE.md

@@ -1,19 +1,26 @@
-# Tool surface — this product
+# Tool surface — Lookout
 
-Policy: **few, powerful, obvious** tools. Prefer the primary read tool first.
+Policy: **few, powerful, obvious** tools.
+
+## Primary
 
 | Tool | Role |
 | --- | --- |
-| `web_search` | Local-first public search adapters |
+| `web_search` | Local-first public search adapters (no paid key required) |
 | `web_fetch` | SSRF-aware fetch |
 | `web_extract` | Main-content extract with citeable spans |
+
+## Advanced
+
+| Tool | Role |
+| --- | --- |
 | `web_cache` | Cache stats/control |
-| `web_crawl` | Advanced crawl |
-| `web_research` | Advanced multi-step research |
+| `web_crawl` | Multi-page crawl |
+| `web_research` | Multi-step research orchestration |
 
 ## Rules
 
-1. Do not add near-duplicate tools that only differ by vanity naming.
+1. Default agent path: **search → fetch → extract**.
 2. Advanced tools must be labeled advanced in README/skill.
-3. Schema fields should be agent-obvious; fail closed on unsafe input.
-4. Composition with sibling products is via public contracts, not monorepo imports.
+3. No paid API key required for primary path.
+4. Local-first means process runs locally; network is inherent to web.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sylphx/lookout",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "description": "Lookout \u2014 local-first web instrument for agents. Search, fetch, extract, cache with citeable excerpts. No required API key. SDK \u00b7 CLI \u00b7 MCP.",
+  "description": "Lookout — local-first web instrument for agents. Search, fetch, extract, cache with citeable excerpts. No required API key. SDK · CLI · MCP.",
   "type": "module",
   "license": "MIT",
   "bin": {

package/server.json

@@ -2,18 +2,18 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.SylphxAI/lookout",
   "title": "Lookout",
-  "description": "Local-first web instrument for agents: search, fetch, extract, cache. No required API key. SDK · CLI · MCP.",
+  "description": "Local-first web instrument for agents: search, fetch, extract, cache. No required API key. SDK \u00b7 CLI \u00b7 MCP.",
   "repository": {
     "url": "https://github.com/SylphxAI/lookout",
     "source": "github"
   },
-  "version": "0.1.0",
+  "version": "0.1.1",
   "websiteUrl": "https://github.com/SylphxAI/lookout#readme",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@sylphx/lookout",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "transport": {
         "type": "stdio"
       }

package/src/doctor.ts

@@ -14,7 +14,7 @@ export function runDoctor(version = '0.1.0'): DoctorReport {
   const checks: DoctorReport['checks'] = [];
   checks.push({
     name: 'core_tools',
-    status: CORE_TOOLS.length === 4 ? 'ok' : 'fail',
+    status: CORE_TOOLS.length === 3 ? 'ok' : 'fail',
     message: `core: ${CORE_TOOLS.join(', ')}; advanced: ${ADVANCED_TOOLS.join(', ')}`,
   });
   const cacheDir = defaultCacheDir();

package/src/engine.ts

@@ -423,5 +423,5 @@ export class LookoutEngine {
   }
 }
 
-export const CORE_TOOLS = ['web_search', 'web_fetch', 'web_extract', 'web_cache'] as const;
-export const ADVANCED_TOOLS = ['web_crawl', 'web_research'] as const;
+export const CORE_TOOLS = ['web_search', 'web_fetch', 'web_extract'] as const;
+export const ADVANCED_TOOLS = ['web_cache', 'web_crawl', 'web_research'] as const;

package/src/mcp.ts

@@ -1,6 +1,6 @@
 /**
  * Lookout MCP server — stdio tools:
- * core: web_search, web_fetch, web_extract, web_cache
+ * core: web_search, web_fetch, web_extract; advanced: web_cache, web_crawl, web_research
  * advanced: web_crawl, web_research
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';