@cubis/foundry 0.3.83 → 0.3.84

package/workflows/skills/playwright-persistent-browser/references/state-management.md

@@ -1,268 +0,0 @@
-# State Management
-
-Load this reference when choosing persistence strategies, serializing browser state, or restoring sessions from saved data.
-
-## State Layers
-
-Browsers store state at multiple layers. Understanding which layer holds your session data determines the persistence strategy.
-
-| Layer | Scope | Persistence API | Typical content |
-| --- | --- | --- | --- |
-| Cookies | Origin + path | `storageState()` | Session IDs, auth tokens, preferences |
-| localStorage | Origin | `storageState()` | User settings, cached data, feature flags |
-| sessionStorage | Origin + tab | Manual extraction | Temporary form data, wizard state |
-| IndexedDB | Origin | Manual extraction | Large datasets, offline cache |
-| Cache API | Origin | Not extractable | HTTP response cache, service worker cache |
-| HTTP cache | Origin | Not extractable | Cached assets (images, scripts, styles) |
-
-## storageState — The Standard Approach
-
-Playwright's `storageState()` captures cookies and localStorage in a single JSON structure.
-
-### Saving state
-
-```typescript
-// Save after authentication
-await context.storageState({ path: 'auth-state.json' });
-```
-
-### Restoring state
-
-```typescript
-// Create a new context with saved state
-const context = await browser.newContext({
-  storageState: 'auth-state.json',
-});
-```
-
-### What storageState captures
-
-```json
-{
-  "cookies": [
-    {
-      "name": "session",
-      "value": "abc123",
-      "domain": ".example.com",
-      "path": "/",
-      "expires": 1710000000,
-      "httpOnly": true,
-      "secure": true,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "https://example.com",
-      "localStorage": [
-        { "name": "theme", "value": "dark" },
-        { "name": "locale", "value": "en-US" }
-      ]
-    }
-  ]
-}
-```
-
-### What storageState does NOT capture
-
-- sessionStorage (tab-scoped, not context-scoped)
-- IndexedDB data
-- Cache API entries
-- Service worker registrations
-- HTTP cache
-- Browser extension state
-
-## sessionStorage Extraction
-
-sessionStorage is scoped to a single tab and is lost when the tab closes. To persist it:
-
-```typescript
-// Extract sessionStorage from a specific page
-const sessionData = await page.evaluate(() => {
-  const data: Record<string, string> = {};
-  for (let i = 0; i < sessionStorage.length; i++) {
-    const key = sessionStorage.key(i)!;
-    data[key] = sessionStorage.getItem(key)!;
-  }
-  return data;
-});
-
-// Save to file
-fs.writeFileSync('session-storage.json', JSON.stringify(sessionData));
-```
-
-```typescript
-// Restore sessionStorage in a new page
-const sessionData = JSON.parse(fs.readFileSync('session-storage.json', 'utf-8'));
-
-await page.addInitScript((data) => {
-  for (const [key, value] of Object.entries(data)) {
-    sessionStorage.setItem(key, value as string);
-  }
-}, sessionData);
-
-await page.goto('https://example.com');
-```
-
-## IndexedDB Extraction
-
-For applications that store significant data in IndexedDB (offline-first apps, PWAs):
-
-```typescript
-// Extract IndexedDB data
-const idbData = await page.evaluate(async () => {
-  const dbNames = await indexedDB.databases();
-  const result: Record<string, any> = {};
-
-  for (const { name } of dbNames) {
-    if (!name) continue;
-    const db = await new Promise<IDBDatabase>((resolve, reject) => {
-      const req = indexedDB.open(name);
-      req.onsuccess = () => resolve(req.result);
-      req.onerror = () => reject(req.error);
-    });
-
-    const stores: Record<string, any[]> = {};
-    for (const storeName of db.objectStoreNames) {
-      const tx = db.transaction(storeName, 'readonly');
-      const store = tx.objectStore(storeName);
-      stores[storeName] = await new Promise((resolve, reject) => {
-        const req = store.getAll();
-        req.onsuccess = () => resolve(req.result);
-        req.onerror = () => reject(req.error);
-      });
-    }
-
-    result[name] = stores;
-    db.close();
-  }
-
-  return result;
-});
-```
-
-## State Validation
-
-Restored state may be invalid (expired tokens, revoked sessions, schema changes). Always validate before using.
-
-### Validation patterns
-
-```typescript
-async function isSessionValid(page: Page): Promise<boolean> {
-  // Pattern 1: Check a protected endpoint
-  const response = await page.goto('https://app.com/api/me');
-  if (!response || response.status() === 401) return false;
-
-  // Pattern 2: Check for login redirect
-  await page.goto('https://app.com/dashboard');
-  if (page.url().includes('/login')) return false;
-
-  // Pattern 3: Check for a logged-in UI element
-  const logoutButton = page.getByRole('button', { name: /log out/i });
-  return await logoutButton.isVisible({ timeout: 3000 }).catch(() => false);
-}
-```
-
-### State freshness check
-
-Add a timestamp to your state file to detect stale state without making a network request:
-
-```typescript
-interface PersistedState {
-  storageState: any;
-  savedAt: string;
-  expiresAt: string;
-}
-
-function isStateExpired(state: PersistedState): boolean {
-  return new Date(state.expiresAt) < new Date();
-}
-```
-
-## Checkpoint Strategy
-
-For long-running workflows, save state at regular intervals:
-
-```typescript
-class CheckpointManager {
-  private interval: NodeJS.Timeout | null = null;
-
-  startPeriodicCheckpoints(context: BrowserContext, filePath: string, intervalMs: number) {
-    this.interval = setInterval(async () => {
-      try {
-        await context.storageState({ path: filePath });
-        console.log(`Checkpoint saved at ${new Date().toISOString()}`);
-      } catch (error) {
-        console.warn('Checkpoint failed:', error);
-      }
-    }, intervalMs);
-  }
-
-  stopCheckpoints() {
-    if (this.interval) {
-      clearInterval(this.interval);
-      this.interval = null;
-    }
-  }
-}
-```
-
-### Checkpoint rotation
-
-Keep multiple checkpoint files to recover from corruption:
-
-```typescript
-async function saveRotatingCheckpoint(
-  context: BrowserContext,
-  baseDir: string,
-  maxCheckpoints: number = 5
-) {
-  const timestamp = Date.now();
-  const filePath = path.join(baseDir, `checkpoint-${timestamp}.json`);
-  await context.storageState({ path: filePath });
-
-  // Remove old checkpoints beyond the limit
-  const files = fs.readdirSync(baseDir)
-    .filter((f) => f.startsWith('checkpoint-'))
-    .sort()
-    .reverse();
-
-  for (const file of files.slice(maxCheckpoints)) {
-    fs.unlinkSync(path.join(baseDir, file));
-  }
-}
-```
-
-## State Migration
-
-When the application changes its storage schema, old state files may become incompatible. Handle this:
-
-```typescript
-interface StateFile {
-  version: number;
-  storageState: any;
-}
-
-function migrateState(state: StateFile): StateFile {
-  if (state.version === 1) {
-    // v1 -> v2: cookie name changed from "sid" to "session_id"
-    state.storageState.cookies = state.storageState.cookies.map((c: any) => ({
-      ...c,
-      name: c.name === 'sid' ? 'session_id' : c.name,
-    }));
-    state.version = 2;
-  }
-  return state;
-}
-```
-
-## Decision Matrix
-
-| Need | Strategy | Complexity |
-| --- | --- | --- |
-| Reuse login across tests | `storageState` in global setup | Low |
-| Persist session across runs | `storageState` to file + validation | Medium |
-| Persist session + form data | `storageState` + sessionStorage extraction | Medium |
-| Persist offline app data | `storageState` + IndexedDB extraction | High |
-| Survive browser restarts | `launchPersistentContext` with user data dir | Medium |
-| Distributed session sharing | `storageState` to Redis/S3 | High |

package/workflows/skills/rag-patterns/SKILL.md

@@ -1,73 +0,0 @@
----
-name: rag-patterns
-description: "Use when designing or optimizing Retrieval-Augmented Generation systems: chunking strategies, embedding model selection, vector store configuration, retrieval optimization, hybrid search, re-ranking, and production RAG pipelines."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# RAG Patterns
-
-## Purpose
-
-Guide the design, implementation, and optimization of production-grade Retrieval-Augmented Generation pipelines. Every instruction ensures that documents are chunked for retrieval quality rather than convenience, embeddings capture semantic meaning, retrieval returns the most relevant context, and the generation model produces grounded answers.
-
-## When to Use
-
-- Designing a RAG pipeline for a new knowledge base or document corpus.
-- Choosing a chunking strategy for a specific document type (code, legal, technical docs).
-- Selecting and configuring embedding models for a domain.
-- Setting up or migrating a vector store (Pinecone, Weaviate, Qdrant, pgvector, Chroma).
-- Optimizing retrieval quality with re-ranking, hybrid search, or query expansion.
-- Debugging RAG systems that produce hallucinated or irrelevant answers.
-- Scaling RAG pipelines for latency, throughput, or cost constraints.
-
-## Instructions
-
-1. **Map the document corpus before choosing a chunking strategy** because the optimal chunk size and boundary rules depend on document structure. Code files need function-level chunks, legal documents need section-level, and conversations need turn-level. A universal chunk size wastes retrieval precision.
-
-2. **Chunk at semantic boundaries, not fixed token counts** because splitting mid-sentence or mid-paragraph destroys the semantic coherence that embeddings rely on. Use headings, paragraph breaks, or AST nodes as natural boundaries, then enforce a token budget as a secondary constraint.
-
-3. **Include overlap between adjacent chunks** because queries often match concepts that span a chunk boundary. 10-15% overlap ensures that boundary-spanning content appears in at least one chunk's embedding.
-
-4. **Attach metadata to every chunk at ingestion time** because retrieval without filtering is a brute-force search. Metadata (source document, section title, date, author, document type) enables filtered retrieval that narrows the search space before vector similarity runs.
-
-5. **Select embedding models based on domain benchmarks, not general leaderboards** because MTEB scores on Wikipedia do not predict performance on your legal contracts or API documentation. Run a retrieval eval on 50-100 representative queries from your domain before committing to a model.
-
-6. **Normalize embedding dimensions when using cosine similarity** because unnormalized vectors distort similarity scores. Most vector stores handle this automatically, but verify the configuration to avoid silent precision loss.
-
-7. **Choose the vector store based on operational requirements, not feature lists** because every store handles millions of vectors but they differ on filtering speed, multi-tenancy support, managed vs. self-hosted operations, and cost at scale. Match the store to your deployment model.
-
-8. **Implement hybrid search combining dense vectors and sparse keyword matching** because dense embeddings excel at semantic similarity but miss exact keyword matches (product codes, error messages, proper nouns). BM25 or sparse vectors catch what dense search misses.
-
-9. **Add a re-ranker between retrieval and generation** because the initial retrieval (top-50 by cosine similarity) optimizes for recall while the generation context window needs precision. A cross-encoder re-ranker reorders by relevance and lets you send only the top-5 to the LLM.
-
-10. **Limit the context window to the most relevant chunks** because stuffing 20 chunks into the prompt dilutes the signal and increases latency and cost. Fewer, higher-quality chunks produce better answers than more, lower-quality ones.
-
-11. **Include source citations in the generation prompt** because grounded answers with traceable citations allow users to verify claims and build trust. Instruct the LLM to reference chunk IDs or document titles in its response.
-
-12. **Build a retrieval evaluation set before optimizing** because retrieval improvements without measurement are guesswork. A set of 50-100 queries with known-relevant documents enables Recall@K and MRR metrics that quantify every change.
-
-13. **Monitor retrieval quality in production with user feedback signals** because offline evals do not capture distribution shift. Track "thumbs down" rates, query reformulations, and zero-result queries to detect degradation.
-
-14. **Cache frequent queries and their retrieval results** because identical or near-identical queries hitting the vector store on every request waste latency and compute. Semantic caching (embedding the query and checking cache similarity) reduces redundant retrievals.
-
-15. **Version your ingestion pipeline alongside the embedding model** because re-indexing is expensive and a model change without full re-indexing creates a mixed-embedding index where similarity scores are meaningless across model versions.
-
-16. **Plan for re-indexing from day one** because embedding models improve, chunking strategies evolve, and metadata schemas change. A pipeline that cannot re-index the full corpus within a maintenance window becomes a legacy liability.
-
-## Output Format
-
-Provide architecture diagrams as ASCII or Mermaid, configuration snippets for vector stores and embedding models, chunking implementation code, retrieval pipeline code, and evaluation results as metric tables.
-
-## References
-
-| File | Load when |
-| --- | --- |
-| `references/chunking.md` | Designing chunking strategies for specific document types. |
-| `references/embedding-models.md` | Selecting, configuring, or fine-tuning embedding models. |
-| `references/vector-stores.md` | Choosing, configuring, or migrating vector stores. |
-| `references/retrieval-optimization.md` | Improving retrieval quality with re-ranking, query expansion, or filtering. |
-| `references/hybrid-search.md` | Implementing hybrid dense + sparse search pipelines. |

package/workflows/skills/rag-patterns/evals/assertions.md

@@ -1,49 +0,0 @@
-# RAG Patterns Eval Assertions
-
-## Eval 1: Chunking Strategy for Technical Docs
-
-This eval tests the skill's ability to design a document-type-aware chunking strategy with proper semantic boundaries, overlap, metadata, and size constraints.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `semantic boundary` -- structure-aware chunking | Fixed-size chunking destroys document structure. Technical docs have headings, sections, and endpoints that define natural chunk boundaries. |
-| 2 | contains | `overlap` -- inter-chunk overlap | Queries matching concepts at chunk boundaries return no results without overlap. 10-15% overlap is standard for retrieval quality. |
-| 3 | contains | `metadata` -- chunk metadata schema | Metadata enables filtered retrieval (e.g., search only API references, filter by version). Without metadata, every query searches the full index. |
-| 4 | contains | `code block` -- code-specific handling | Code examples are atomic units. A function split across two chunks is useless for developer Q&A. The strategy must keep code blocks intact. |
-| 5 | contains | `token` -- token-based size constraints | Character-based limits do not account for tokenizer behavior. Embedding models have token limits, and the LLM context window is measured in tokens. |
-
-### What a passing response looks like
-
-- Three distinct chunking strategies for the three document types (API refs, tutorials, changelogs).
-- API references chunked by endpoint (one chunk per operation with description, parameters, and response schema).
-- Tutorials chunked by section with heading-based boundaries, code blocks kept intact, and 10-15% overlap.
-- Changelogs chunked by release version.
-- A metadata schema with fields: doc_type, title, section, version, api_endpoint (nullable), language (for code).
-- Chunk size target of 256-512 tokens with a hard ceiling and soft floor.
-- A code-block preservation rule: if a code block would push the chunk over the limit, the code block becomes its own chunk with the preceding paragraph as context.
-
----
-
-## Eval 2: Hybrid Search Implementation
-
-This eval tests the skill's ability to implement a complete hybrid search pipeline with dense + sparse retrieval, fusion scoring, and re-ranking.
-
-### Assertions
-
-| # | Type | What it checks | Why it matters |
-|---|------|----------------|----------------|
-| 1 | contains | `BM25` -- sparse retrieval component | Dense embeddings encode meaning but miss exact lexical matches. Error codes like "ERR-4502" and SKUs need keyword matching. |
-| 2 | contains | `fusion` -- result merging strategy | Dense and sparse retrievers return separate ranked lists. Without a principled fusion strategy, the pipeline cannot combine their strengths. |
-| 3 | contains | `re-rank` -- cross-encoder re-ranking | Initial retrieval optimizes for recall (find everything that might be relevant). Re-ranking optimizes for precision (put the best results first). |
-| 4 | contains | `Qdrant` -- vector store implementation | The eval specifies Qdrant. The implementation must use Qdrant's sparse vector support or payload indexing, not a generic abstraction. |
-| 5 | contains | `weight` -- configurable fusion weights | The optimal dense/sparse balance varies by query type. Keyword-heavy queries need more sparse weight; conceptual queries need more dense weight. |
-
-### What a passing response looks like
-
-- An indexing pipeline that stores both dense vectors and sparse representations (BM25 or SPLADE) in Qdrant.
-- A query pipeline that: (a) embeds the query with the dense model, (b) generates a sparse query representation, (c) retrieves top-50 from each, (d) fuses results with RRF or weighted scoring, (e) re-ranks top-20 with a cross-encoder, (f) returns top-5 to the LLM.
-- Qdrant-specific configuration showing named vectors or sparse vector fields.
-- Configurable weights with a sensible default (e.g., 0.6 dense, 0.4 sparse) and guidance on tuning.
-- A worked example showing how "error code ERR-4502 payment failed" benefits from hybrid search vs. dense-only.

package/workflows/skills/rag-patterns/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "chunking-strategy-for-technical-docs",
-    "description": "Validate that the skill produces a well-reasoned chunking strategy for technical documentation, covering semantic boundaries, overlap, metadata, and size constraints appropriate for the document type.",
-    "input": "Design a chunking strategy for a technical documentation corpus that includes API references (OpenAPI specs), tutorial guides (markdown with code blocks), and changelog entries. The corpus has 5,000 documents totaling 50 million tokens. The target vector store is Pinecone with a 512-dimension embedding model. Chunks will be used for a developer-facing Q&A chatbot. Provide the chunking logic, metadata schema, and recommended chunk sizes.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "semantic boundary",
-        "description": "The strategy must chunk at semantic boundaries (headings, sections, function definitions) rather than fixed token counts, because technical docs have natural structure that should be preserved."
-      },
-      {
-        "type": "contains",
-        "value": "overlap",
-        "description": "The strategy must include chunk overlap (10-15%) to handle queries that match concepts spanning adjacent chunks in tutorials and guides."
-      },
-      {
-        "type": "contains",
-        "value": "metadata",
-        "description": "The strategy must define a metadata schema attached to each chunk (document type, section title, API endpoint, version) to enable filtered retrieval."
-      },
-      {
-        "type": "contains",
-        "value": "code block",
-        "description": "The strategy must address code blocks specifically, because splitting a code example across chunks destroys its utility for developer Q&A."
-      },
-      {
-        "type": "contains",
-        "value": "token",
-        "description": "The strategy must specify chunk size constraints in tokens (not just characters) to align with the embedding model's context window and the LLM's generation budget."
-      }
-    ]
-  },
-  {
-    "name": "hybrid-search-implementation",
-    "description": "Validate that the skill produces a hybrid search implementation combining dense vector search with sparse keyword matching, including fusion scoring, re-ranking, and configuration for a production deployment.",
-    "input": "Implement a hybrid search pipeline for a customer support knowledge base. The system must handle queries like 'error code ERR-4502 payment failed' where both semantic meaning and exact keyword matching matter. The current dense-only retrieval misses exact error codes and product SKUs. Use Qdrant as the vector store. Provide the indexing pipeline, query pipeline, and fusion scoring logic.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "BM25",
-        "description": "The implementation must include BM25 or equivalent sparse retrieval to capture exact keyword matches that dense embeddings miss (error codes, SKUs, proper nouns)."
-      },
-      {
-        "type": "contains",
-        "value": "fusion",
-        "description": "The pipeline must include a fusion step (RRF, weighted combination, or similar) that merges dense and sparse results into a single ranked list."
-      },
-      {
-        "type": "contains",
-        "value": "re-rank",
-        "description": "The pipeline must include a re-ranking step after fusion to refine the top-K results using a cross-encoder or similar model before sending context to the LLM."
-      },
-      {
-        "type": "contains",
-        "value": "Qdrant",
-        "description": "The implementation must use Qdrant as specified and demonstrate its sparse vector or payload indexing capabilities for the keyword matching component."
-      },
-      {
-        "type": "contains",
-        "value": "weight",
-        "description": "The fusion scoring must include configurable weights for dense vs. sparse components, because the optimal balance depends on query distribution and must be tunable."
-      }
-    ]
-  }
-]