@agent-smith/core 0.0.1 → 0.0.2

package/dist/agents/read.js

@@ -1,13 +1,12 @@
-import path from "path";
 import { compile, serializeGrammar } from "@intrinsicai/gbnfgen";
-import { readSkillsFromList, readTool } from "../db/read.js";
+import path from "path";
 import { executeAction } from "../actions/cmd.js";
+import { readSkillsFromList, readTool } from "../db/read.js";
 import { McpClient } from "../mcp.js";
+import { openAgentSpec } from "../utils/io.js";
 import { executeWorkflow } from "../workflows/cmd.js";
 import { executeAgent } from "./cmd.js";
-import { openAgentSpec } from "../utils/io.js";
 import { applyFilePlaceholders } from "./files.js";
-//import { confirmToolUsage } from "../tools.js";
 async function readAgent(name, payload, options) {
     /*console.log("Read Agent", name);
     console.log("Payload:", payload);

package/dist/features/agents/agent-smith-assistant.yml

@@ -0,0 +1,32 @@
+description: An agent to manage Agent Smith's documentation
+category: builtin
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith assistant, an AI agent. You can run other agents to do jobs using the `run-agent` tool with the agent `agent-smith-assistant`, a fork of yourself.
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - load-skill
+  - read-webpage
+  - run-agent

package/dist/features/agents/agent-smith-code.yml

@@ -0,0 +1,31 @@
+description: An agent to manage Agent Smith's documentation
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized agents. Your job is to organise the workflow and delegate taks to specialized agents to orchestrate the work. 
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: read this to find documentation
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - agent-smith-doc

package/dist/features/agents/agent-smith-colab.yml

@@ -1,20 +1,19 @@
 description: An agent to manage Agent Smith's documentation
-category: internal
+category: builtin
 prompt: |-
     {prompt}
 template:
     system: |-
-      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized collaborators. Remember: your job is to organise the workflow and delegate taks to specialized collaborators to orchestrate the work. 
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You can run in main agent mode or collaborator mode. Your job is to organise the workflow when in main agent mode and delegate taks to specialized collaborators to orchestrate the work.
 
-      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need.
-      Important: you can only run collaborators when you are not already in collaborator mode. Run them one at the time.
+      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need. You can only run collaborators when you are in main agent mode. Run them one at the time.
 
       {file:../fragments/workspace.txt}
 
       {file:../fragments/ctx-helper-files.md}
       - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation
 
-      Evaluate the user request and organise the work of collaborators to get an answer.
+      Evaluate the request. Execute it if you are in collaborator mode, or and organise the work of collaborators if you are in main agent mode.
 model: qwen35b
 backend: llamaccp
 inferParams:

package/dist/features/agents/agent-smith-doc-colab.yml

@@ -0,0 +1,54 @@
+tool:
+  name: agent-smith-doc-colab
+  description: An agent to manage Agent Smith project's documentation
+  arguments:
+      prompt:
+          description: The query about the documentation, the task to perform
+          required: true
+description: An agent to manage Agent Smith's documentation
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a documentation agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized collaborators. Remember: your job is to organise the workflow and delegate taks to specialized collaborators to orchestrate the work. 
+
+      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need.
+      Important: you can only run collaborators when you are not already in collaborator mode. Run them one at the time.
+
+      In addition to your tools you are provided with some skills: these are instructions to accomplish specific tasks. Here are the available skills and instructions about when to use them:
+
+      {skills}
+
+      You can choose to use a skill using the `load-skill` tool when it matches the task. Loading the skill will provide you with instructions to follow about how to accomplish the specific task it was made for.
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. 
+      Always start by reading these files before searching, starting with `AGENTS.md`.
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  #- notify-user
+  - run-collaborator
+skills:
+  - update-doc-map
+  - update-codebase-summary
+  - document-package
+  - create-readme

package/dist/features/agents/agent-smith-doc.yml

@@ -20,9 +20,9 @@ template:
       You can choose to use a skill using the `load-skill` tool when it matches the task. Loading the skill will provide you with instructions to follow about how to accomplish the specific task it was made for.
 
       {file:../fragments/workspace.txt}
-
       {file:../fragments/ctx-helper-files.md}
-      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. Always start by reading this before searching.
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. 
+      Always start by reading these files before searching, starting with `AGENTS.md`.
 model: qwen35b
 backend: llamaccp
 inferParams:
@@ -31,7 +31,6 @@ inferParams:
     top_p: 0.85
     temperature: 0.6
     repetition_penalty: 1
-    presence_penalty: 1.5
     chat_template_kwargs:
       enable_thinking: true
       preserve_thinking: true
@@ -47,4 +46,4 @@ skills:
   - update-doc-map
   - update-codebase-summary
   - document-package
-  - create-package-readme
+  - create-readme

package/dist/features/agents/agent-smith-help.yml

@@ -1,5 +1,5 @@
 description: An agent to manage Agent Smith's documentation
-category: doc
+category: builtin
 prompt: |-
     {prompt}
 template:
@@ -14,7 +14,7 @@ template:
       {file:../fragments/workspace.txt}
       {file:../fragments/ctx-helper-files.md}
       
-      Information about the database: agent-smith/docsite/public/doc/architecture/3.database.md. 
+      Information about the database: `agent-smith/docsite/public/doc/architecture/3.database.md`. 
       Important: to read any agents, actions and other builtin features always use the "read-feature" tool if you need to read one. For other files use the "shell" tool.
 
       Read AGENTS.md, the project nav file and the database info file before all to get a good idea of the context
@@ -24,6 +24,10 @@ inferParams:
     top_k: 20
     top_p: 0.85
     temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
 variables:
   required:
     workspace:

package/dist/features/agents/agent-smith-search.yml

@@ -1,11 +1,11 @@
 tool:
   name: agent-smith-search
-  description: An agent to run web search
+  description: run web search or open web pages
   arguments:
       prompt:
           description: the web search to perform or question about a web page
           required: true
-description: An agent to run web search
+description: An agent to run web search or open web pages
 category: internal
 prompt: |-
     {prompt}
@@ -26,7 +26,6 @@ inferParams:
     top_p: 0.85
     temperature: 0.6
     repetition_penalty: 1
-    presence_penalty: 1.5
     chat_template_kwargs:
       enable_thinking: true
       preserve_thinking: true
@@ -38,4 +37,4 @@ toolsList:
   - shell
   - python
   - ddsearch
-  - open_page
+  - read-webpage

package/dist/features/agents/agent-smith-sql.yml

@@ -1,8 +1,8 @@
 tool:
-    description: Create a database query for Agent Smith database
+    description: retrieve data from the Agent Smith config database that references agents, actions, workflows and other features
     arguments:
         prompt: 
-            description: The user question to create a query from
+            description: the question about the config or data to retrieve
 description: Create an sql query
 category: internal
 prompt: |-

package/dist/features/agents/agent-smith.yml

@@ -1,19 +1,22 @@
 description: An agent to manage Agent Smith's documentation
-category: internal
+category: builtin
 prompt: |-
     {prompt}
 template:
     system: |-
-      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized agents. Available subagents:
+      You are Agent Smith, an AI coordinator agent. Your job is to organise the workflow of other agents. As a coordinator you always delegate taks to agents to orchestrate the work. Your job is to coordinate the team of agents. Available agents:
 
-        - `agent-smith-doc`: a documentation manager agent. Use it for all documentation related tasks, like verify, create or update documentation. It has specific skills to create codebase summaries and manage documentation.
-        - `agent-smith-search`: a web search and web page reader agent. Use to search information or ask questions about some web pages.
-
-      Agents call mode info: you can call an agent in worker mode using `run-worker`, it will have all the context you have in the conversation history. Or you can call an agent in isolation mode using `run-agent`: the agent will be completly independant and have no context. Use the isolation mode for independant tasks that are heavy and do not require context, otherwise use the worker mode to share context and dialog with workers.
+      - `agent-smith-assistant`: a fork of yourself, the default agent. Run it by default to accomplish any task.
+      - `agent-smith-search`: a web search and web page reader agent. Use to search information or for questions about some web pages.
 
       {file:../fragments/workspace.txt}
       {file:../fragments/ctx-helper-files.md}
-      - `agent-smith/.agents/documentation/documentation-map.md`: read this to find documentation
+
+      Your workflow to answer a user request:
+
+      - Analyze the user request
+      - Decompose the task to subtasks if necessary and plan the work to do
+      - Call agent(s) one after the other to accomplish the subtasks, use `agent-smith-assistant` by default if no specialized agent matches. Only call one agent at the time.
 model: qwen35b
 backend: llamaccp
 inferParams:
@@ -33,5 +36,6 @@ variables:
 toolsList:
   - shell
   - python
-  - run-worker
-  - run-agent
+  - run-agent
+  - load-skill
+  - notify-user

package/dist/features/agents/collaborator.yml

@@ -1,5 +1,6 @@
 description: A collaborator agent
-type: builtin
+category: internal
+type: worker
 prompt: |-
     You are on collaborator mode. Your role is: {role}. Main agent request:
 

package/dist/features/fragments/call-mode.md

@@ -0,0 +1,3 @@
+Agents call mode info: you can call an agent in worker mode using `run-worker`, it will have all the context you have in the conversation history. Or you can call an agent in isolation mode using `run-agent`: the agent will be completly independant and have no context. Use the isolation mode for independant tasks that are heavy and do not require context, otherwise use the worker mode to share context and dialog with workers.
+
+Evaluate if you run in worker mode. If yes answer directly. Otherwise if in main agent mode coordinate the work.

package/dist/features/fragments/ctx-helper-files.md

@@ -1,4 +1,4 @@
 Project's context helper files:
 
-- `AGENTS.md`: general high level context map of the project
+- `AGENTS.md`: general high level context map of the project. Read this first.
 - `.agents/documentation/project-nav.md`: a map of the project repositories and overview of the project

package/dist/features/skills/create-readme/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: create-readme
+description: use this to create comprehensive README file for a given package or plugin or repository
+---
+
+## Workflow: README Creation
+
+### Phase 1: Discovery
+1. Read `/workspace/AGENTS.md` and `/workspace/.agents/documentation/project-nav.md` to understand project structure
+2. Read `/workspace/agent-smith/.agents/documentation/codebase-summary.md` and `/workspace/agent-smith/.agents/documentation/dpcumentation-map.md`
+3. Locate target in the codebase summary (note its position, dependencies, and purpose)
+
+### Phase 2: Deep Dive
+3. Navigate to directory: `/workspace/agent-smith/packages/{package-name}/` for a package, adapt the path
+4. Read `.agents/documentation/codebase-summary.md` for architecture, key files, and usage patterns
+5. Read documentation from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/*.md` (get_started, usage, api)
+
+### Phase 3: Synthesis & Writing
+6. Create `README.md` with this structure:
+   - **Npm badge**: example:
+      ```
+      [![pub package](https://img.shields.io/npm/v/this-package-name)](https://www.npmjs.com/package/this-package-name)
+      ```
+   - **Title & Tagline**: Package name + one-sentence description. Mention that this package is part of the Agent Smith toolkit (repository: https://github.com/lynxai-team/agent-smith)
+   - **Features**: Bullet list of key capabilities (use emojis for visual hierarchy)
+   - **Documentation**: REQUIRED section with specific structure (see below)
+   - **Installation**: npm/yarn command in code block
+   - **Quick Start**: Minimal working example showing creation, init, and basic operations
+   - **Usage**: Detailed patterns with code examples (creation, initialization, verbose mode, reading/writing, error handling)
+   - **Complete Example**: Full working async function demonstrating all operations
+   - **API Reference**: Factory function signature + parameters table + interface + method summary table
+   - **Important Notes**: Browser-only warnings, limitations, related packages
+   - **Documentation Links**: References to full docsite
+   - **License**: MIT/appropriate license
+
+### Documentation Section Structure (REQUIRED)
+
+Every README must include a **Documentation** section with this exact structure: two subsections — "For AI Agents" and "For Humans" — providing appropriate links for each audience.
+
+#### Required Format
+
+```markdown
+## Documentation
+
+### For AI Agents
+- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the {package-name} package
+- [Doc1](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/{package-name}/1.get_started.md) — Description
+- [Doc2](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/{package-name}/2.topic.md) — Description
+
+### For Humans
+- [Doc1](https://lynxai-team.github.io/agent-smith/libraries/{package-name}/) — Description
+- [Doc2](https://lynxai-team.github.io/agent-smith/libraries/{package-name}/topic) — Description
+```
+
+#### Rules
+
+1. **For AI Agents subsection**:
+   - Always start with a link to `.agents/documentation/codebase-summary.md` (relative path)
+   - List all relevant documentation files from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/`
+   - Use raw GitHub URLs: `https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/{package-name}/{filename}.md`
+   - Include a brief description after each link (after `—`)
+
+2. **For Humans subsection**:
+   - Use the docsite URL: `https://lynxai-team.github.io/agent-smith/libraries/{package-name}/`
+   - Convert paths: replace `docsite/public/doc/libraries/{package-name}/` with `libraries/{package-name}/`
+   - Remove file numbering prefixes (e.g., `1.get_started.md` → `/`)
+   - Include a brief description after each link (after `—`)
+
+#### Example from the types package README
+
+```markdown
+## Documentation
+
+### For AI Agents
+- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the Agent Smith libraries
+- [Get Started](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/types/1.get_started.md) — Overview and installation
+- [Interfaces](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/types/2.interfaces.md) — Complete API reference of all exported types
+
+### For Humans
+- [Get Started](https://lynxai-team.github.io/agent-smith/libraries/types/) — Overview and usage guide
+- [Interfaces](https://lynxai-team.github.io/agent-smith/libraries/types/interfaces) — Full interface reference with tables
+```
+
+### Key Principles
+- **Information Density**: Every section must convey unique value; avoid repetition between Quick Start and Usage
+- **Code Examples**: All examples must be complete, runnable TypeScript with proper async/await
+- **Type Safety**: Show generic type parameters explicitly (e.g., `get<string>()`)
+- **Error Handling**: Document error cases explicitly with try/catch examples
+- **Browser vs Node**: Clearly state environment constraints early in the README
+- **Visual Hierarchy**: Use emojis for feature bullets, clear section headers, and tables for API reference
+
+### Output Validation
+Before finalizing, verify:
+- [ ] All code blocks are syntactically valid TypeScript
+- [ ] API signatures match actual implementation (check source files if needed)
+- [ ] Installation command uses correct package name (`@agent-smith/{package-name}`)
+- [ ] Documentation section follows the required structure with "For AI Agents" and "For Humans" subsections
+- [ ] Documentation links follow consistent pattern (raw GitHub URLs for AI agents, docsite URLs for humans)
+- [ ] No internal paths or implementation details leak into public documentation
+
+Documentation links base url: https://lynxai-team.github.io/agent-smith/
+
+Notify the user when the task is completed

package/dist/features/skills/t/SKILL.md

@@ -11,10 +11,12 @@ The tasks are located in an `.agents/tasks` directory, or `[project-name].agents
 
 Read `.agents/tasks/[task-name]` to list the task files. If a `state.md` file is there read it: it details the task progression.
 
-## Write to a task
+## Create or update a task
 
 Check if an `.agents/tasks/[task-name]` directory exists, if not create it. You can write markdown files in it.
 
+When asked to create a task do it and then report to the user before executing the task
+
 ## Execute or continue a task
 
 Check what is remaining to do. Avoid verifying previous phases and execute the next phase directly. Always execute the phases one by one. Update the sate after each phase to mark it done.

package/dist/features/workflows/agent-smith-db.yml

@@ -1,5 +1,5 @@
 tool:
-  description: and sql agent to retrieve data in the Agent Smith database by asking a question in natural language and get the data back
+  description: and agent to retrieve data in the Agent Smith config database that references agents, actions, workflows and other features. Ask a question in natural language and get the data back. 
   arguments:
     prompt:
         description: the question to ask about the data

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@agent-smith/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Agent Smith core",
   "repository": "https://github.com/synw/agent-smith",
   "scripts": {
     "build": "rm -rf dist/* && tsc && cp -r src/features/agents dist/features && cp -r src/features/workflows dist/features && cp -r src/features/fragments dist/features && cp -r src/features/skills dist/features"
   },
   "dependencies": {
-    "@agent-smith/agent": "^0.5.0",
+    "@agent-smith/agent": "^0.5.1",
     "@intrinsicai/gbnfgen": "^0.12.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@vue/reactivity": "^3.5.35",
@@ -21,7 +21,7 @@
   "devDependencies": {
     "@agent-smith/types": "^0.0.5",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@types/node-notifier": "^8.0.5",
     "tslib": "^2.8.1",
     "typescript": "^6.0.3"

package/dist/features/skills/create-package-readme/SKILL.md

@@ -1,66 +0,0 @@
----
-name: create-package-readme
-description: use this to create comprehensive README file for a given package
----
-
-## Workflow: Package README Creation
-
-### Phase 1: Discovery
-1. Read `/workspace/AGENTS.md` and `/workspace/.agents/documentation/project-nav.md` to understand project structure
-2. Read `/workspace/agent-smith/.agents/documentation/codebase-summary.md` and `/workspace/agent-smith/.agents/documentation/dpcumentation-map.md`
-3. Locate target package in the codebase summary (note its position, dependencies, and purpose)
-
-### Phase 2: Deep Dive
-3. Navigate to package directory: `/workspace/agent-smith/packages/{package-name}/`
-4. Read `.agents/documentation/codebase-summary.md` for package-specific architecture, key files, and usage patterns
-5. Read documentation from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/*.md` (get_started, usage, api)
-
-### Phase 3: Synthesis & Writing
-6. Create `/workspace/agent-smith/packages/{package-name}/README.md` with this structure:
-   - **Npm badge**: example:
-      ```
-      [![pub package](https://img.shields.io/npm/v/this-package-name)](https://www.npmjs.com/package/this-package-name)
-      ```
-   - **Title & Tagline**: Package name + one-sentence description. Mention that this package is part of the Agent Smith toolkit (repository: https://github.com/lynxai-team/agent-smith)
-   - **Features**: Bullet list of key capabilities (use emojis for visual hierarchy)
-   - **Documentation**: 2 sections: documentation for AI agents (must include a link to the codebase navigation map at .agents/documentation/codebase-summary.md and the relevant doc from documentation), and documentation for humans, with the relevant doc http links. Correct links formats:
-      - For humans use the site link: https://lynxai-team.github.io/agent-smith/: replace the `docsite/public/doc` paths by this link. Example:
-         ```md
-         - [Complete doc](https://lynxai-team.github.io/agent-smith/libraries/agent/)
-         ```
-      - For AI agents provide detailled links map and use the raw file paths links. Example:
-         ```md
-         - [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the agent package
-         - [Get Started](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/1.get_started.md) — Installation and basic usage
-         - [Tools](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/2.tools.md) — Defining and configuring tools for agents
-         - [Templates](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/3.templates.md) — System prompts, YAML specs, and few-shot examples
-         - [Supervision](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/4.supervision.md) — Human-in-the-loop tool authorization
-         ```
-   - **Installation**: npm/yarn command in code block
-   - **Quick Start**: Minimal working example showing creation, init, and basic operations
-   - **Usage**: Detailed patterns with code examples (creation, initialization, verbose mode, reading/writing, error handling)
-   - **Complete Example**: Full working async function demonstrating all operations
-   - **API Reference**: Factory function signature + parameters table + interface + method summary table
-   - **Important Notes**: Browser-only warnings, limitations, related packages
-   - **Documentation Links**: References to full docsite
-   - **License**: MIT/appropriate license
-
-### Key Principles
-- **Information Density**: Every section must convey unique value; avoid repetition between Quick Start and Usage
-- **Code Examples**: All examples must be complete, runnable TypeScript with proper async/await
-- **Type Safety**: Show generic type parameters explicitly (e.g., `get<string>()`)
-- **Error Handling**: Document error cases explicitly with try/catch examples
-- **Browser vs Node**: Clearly state environment constraints early in the README
-- **Visual Hierarchy**: Use emojis for feature bullets, clear section headers, and tables for API reference
-
-### Output Validation
-Before finalizing, verify:
-- [ ] All code blocks are syntactically valid TypeScript
-- [ ] API signatures match actual implementation (check source files if needed)
-- [ ] Installation command uses correct package name (`@agent-smith/{package-name}`)
-- [ ] Documentation links follow consistent pattern
-- [ ] No internal paths or implementation details leak into public documentation
-
-Documentation links base url: https://lynxai-team.github.io/agent-smith/
-
-Notify the user when the task is completed