npcsh 1.1.14__tar.gz → 1.1.15__tar.gz

{npcsh-1.1.14 → npcsh-1.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.1.14
+Version: 1.1.15
 Summary: npcsh is a command-line toolkit for using AI agents in novel ways.
 Home-page: https://github.com/NPC-Worldwide/npcsh
 Author: Christopher Agostino
@@ -100,12 +100,14 @@ Dynamic: summary
 
 <p align="center">
   <a href= "https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md"> 
-  <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/npcsh/npcsh.png" alt="npcsh logo" width=250></a>
+  <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/npcsh/npcsh.png" alt="npcsh logo" width=600></a>
 </p> 
 
 # NPC Shell
 
-The NPC shell is the toolkit for tomorrow, providing a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. `npcsh` is based in the command line, and so can be used wherever you work. 
+`npcsh` - a new standard in human-agent interaction. Co-create with agents to build organizations that refine themselves and evolve to your needs.
+
+The NPC shell is a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. Based in the command line, use it wherever you work. 
 
 - It is developed to work reliably with small models and performs excellently with the state-of-the-art models from major model providers. 
 - Fundamentally, the core program of npcsh extends the familiar bash environment with an intelligent layer that lets users seamlessly ask agents questions, run pre-built or custom macros or agents, all without breaking the flow of command-line work.
@@ -125,7 +127,7 @@ Once installed: run
 ```bash
 npcsh
 ```
-and you will enter the NPC shell. Additionally, the pip installation includes the following CLI tools available in bash: `corca`, `guac`, `npc` cli, `pti`, `spool`, `wander`, and`yap`. 
+and you will enter the NPC shell. Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
 
 
 # Usage
@@ -204,10 +206,19 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
         <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=250>
       </p> 
 
-  - **Serve an NPC Team**
+  - **Serve an NPC Team** (Agentic API Server)
     ```bash
     /serve --port 5337 --cors='http://localhost:5137/'
     ```
+    This exposes your NPC team as a full agentic server with:
+    - **OpenAI-compatible endpoints** for drop-in LLM replacement
+      - `POST /v1/chat/completions` - Chat with NPCs (use `agent` param to select NPC)
+      - `GET /v1/models` - List available NPCs as models
+    - **NPC management**
+      - `GET /npcs` - List team NPCs with their capabilities
+      - `POST /chat` - Direct chat with NPC selection
+    - **Jinx controls** - Execute jinxs remotely via API
+    - **Team orchestration** - Delegate tasks and convene discussions programmatically
   - **Screenshot Analysis**: select an area on your screen and then send your question to the LLM
     ```bash
     /ots
@@ -217,7 +228,7 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
     /corca --mcp-server-path /path.to.server.py
     ```
 
-  - **Build an NPC Team**: 
+  - **Build an NPC Team**:
 
     ``` bash
     npc build flask --output ./dist --port 5337
@@ -226,6 +237,28 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
     npc build static --api_url https://api.example.com
     ```
 
+  - **NQL - AI-Powered SQL Models**:
+    Run SQL models with embedded AI transformations using NPC agents:
+    ```bash
+    # List available models
+    nql show=1
+
+    # Run all models in dependency order
+    nql
+
+    # Run a specific model
+    nql model=daily_summary
+
+    # Schedule with cron (runs daily at 6am)
+    nql install_cron="0 6 * * *"
+    ```
+
+  - **Visualize Team Structure**:
+    ```bash
+    npc teamviz save=team_structure.png
+    ```
+    Generates network and ordered views showing NPCs, jinxs, and their relationships.
+
 # NPC Data Layer
 
 The core of npcsh's capabilities is powered by the NPC Data Layer. Upon initialization, a user will be prompted to make a team in the current directory or to use a global team stored in `~/.npcsh/` which houses the NPC team with its jinxs, models, contexts, assembly lines. By implementing these components as simple data structures, users can focus on tweaking the relevant parts of their multi-agent systems.
@@ -237,6 +270,7 @@ Users can extend NPC capabilities through simple YAML files:
 - **NPCs** (.npc): are defined with a name, primary directive, and optional model specifications
 - **Jinxs** (.jinx): Jinja execution templates that provide function-like capabilities and scaleable extensibility through Jinja references to call other jinxs to build upon. Jinxs are executed through prompt-based flows, allowing them to be used by models regardless of their tool-calling capabilities, making it possible then to enable agents at the edge of computing through this simple methodology.
 - **Context** (.ctx): Specify contextual information, team preferences, MCP server paths, database connections, and other environment variables that are loaded for the team or for specific agents (e.g. `GUAC_FORENPC`). Teams are specified by their path and the team name in the `<team>.ctx` file. Teams organize collections of NPCs with shared context and specify a coordinator within the team context who is used whenever the team is called upon for orchestration.
+- **SQL Models** (.sql): NQL (NPC Query Language) models combine SQL with AI-powered transformations. Place `.sql` files in `npc_team/models/` to create data pipelines with embedded LLM calls.
 
 The NPC Shell system integrates the capabilities of `npcpy` to maintain conversation history, track command execution, and provide intelligent autocomplete through an extensible command routing system. State is preserved between sessions, allowing for continuous knowledge building over time.
 
@@ -244,40 +278,334 @@ This architecture enables users to build complex AI workflows while maintaining
 
 Importantly, users can switch easily between the NPCs they are chatting with by typing `/n npc_name` within the NPC shell. Likewise, they can create Jinxs and then use them from within the NPC shell by invoking the jinx name and the arguments required for the Jinx;  `/<jinx_name> arg1 arg2`
 
-# Jinx as macros
--  activated by invoking `/<jinx_name> ...` in `npcsh`, jinxs can be called in bash or through the `npc` CLI. In our examples, we provide both `npcsh` calls as well as bash calls with the `npc` cli where relevant. For converting any `/<command>` in `npcsh` to a bash version, replace the `/` with `npc ` and the macro command will be invoked as a positional argument. 
-    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
-    - `/build` - Builds the current npc team to an executable format . Usage: `/build <output[flask,docker,cli,static]> --options`
-    - `/breathe` - Condense context on a regular cadence. Usage: `/breathe -p <provider: NPCSH_CHAT_PROVIDER> -m <model: NPCSH_CHAT_MODEL>`
-    - `/compile` - Compile NPC profiles. Usage: `/compile <path_to_npc> `
-    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: `/corca [--mcp-server-path path]`                  
-    - `/guac` - Enter guac mode. Usage: `/guac`
-    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: `/help`
-    - `/init` - Initialize NPC project. Usage: `/init`
-    - `/jinxs` - Show available jinxs for the current NPC/Team. Usage: `/jinxs`
-    - `/<jinx_name>` - Run a jinx with specified command line arguments. `/<jinx_name> jinx_arg1 jinx_arg2`
-    - `/npc-studio` - Start npc studio. Pulls NPC Studio github to `~/.npcsh/npc-studio` and launches it in development mode after installing necessary NPM dependencies.Usage: `/npc-studio`
-    - `/ots` - Take screenshot and analyze with vision model. Usage: `/ots filename=<output_file_name_for_screenshot>` then select an area, and you will be prompted for your request.
-    - `/plonk` - Use vision model to interact with GUI. Usage: `/plonk '<task description>' `
-    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM. Usage: `/pti`
-    - `/roll` - generate a video with video generation model. Usage: `/roll '<description_for_a_movie>' --vgmodel <NPCSH_VIDEO_GEN_MODEL> --vgprovider <NPCSH_VIDEO_GEN_PROVIDER>`
-    - `/sample` - Send a context-free prompt to an LLM, letting you get fresh answers without needing to start a separate conversation/shell. Usage: `/sample -m <NPCSH_CHAT_MODEL> 'question to sample --temp <float> --top_k int`
-    - `/search` - Execute a search command on the web, in your memories, in the knowledge graph, or in documents with rag. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo, Perplexity, and Exa with more coming soon through litellm. Wikipedia integration ongoing. See above for more search specific examples.
-    - `/serve` - Serve an NPC Team server. 
-    - `/set` - Set configuration values. 
-      - Usage: 
-        - `/set model gemma3:4b`, 
-        - `/set provider ollama`, 
-        - `/set NPCSH_VIDEO_GEN_PROVIDER diffusers`
-    - `/sleep` - Evolve knowledge graph with options for dreaming.  Usage: `/sleep --ops link_facts,deepen`
-    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag. Usage: `/spool --attachments 'path1,path2,path3' -n <npc_name> -m <modell> -p <provider>`
-    - `/trigger` - Execute a trigger command.  Usage: `/trigger 'a description of a trigger to implement with system daemons/file system listeners.' -m gemma3:27b -p ollama`
-    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini. 
-      - Usage: 
-        - Gen Image: `/vixynt -igp <NPCSH_IMAGE_GEN_PROVIDER> --igmodel <NPCSH_IMAGE_GEN_MODEL> --output_file <path_to_file> width=<int:1024> height =<int:1024> 'description of image`
-        - Edit Image: `/vixynt 'edit this....' --attachments '/path/to/image.png,/path/to/image.jpeg'`
-    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature.  Usage: `/wander 'query to wander about' --provider "ollama" --model "deepseek-r1:32b" environment="a vast dark ocean" interruption-likelihood=.1`
-    - `/yap` - Enter voice chat (yap) mode. Usage: `/yap -n <npc_to_chat_with>`
+# Team Orchestration
+
+NPCs work together through orchestration patterns. The **forenpc** (specified in your team's `.ctx` file) acts as the coordinator, delegating tasks to specialized NPCs and convening group discussions.
+
+## How NPCs and Jinxs Relate
+
+Each NPC has a set of **jinxs** they can use, defined in their `.npc` file:
+
+```yaml
+# corca.npc
+name: corca
+primary_directive: "You are a coding specialist..."
+model: claude-sonnet-4-20250514
+provider: anthropic
+jinxs:
+  - lib/core/python
+  - lib/core/sh
+  - lib/core/edit_file
+  - lib/core/search
+```
+
+When an NPC is invoked, they can only use the jinxs assigned to them. This creates **specialization**:
+- `corca` has coding tools (python, sh, edit_file)
+- `plonk` has browser automation (browser_action, screenshot)
+- `alicanto` has research tools (arxiv, semantic_scholar, paper_search)
+- `frederic` has generation tools (vixynt, roll, sample)
+
+The forenpc (orchestrator) can delegate to any team member based on their specialization.
+
+## Delegation with Review Loop
+
+The `/delegate` jinx sends a task to another NPC with automatic review and feedback:
+
+```bash
+/delegate npc_name=corca task="Write a Python function to parse JSON files" max_iterations=5
+```
+
+**How it works:**
+1. The orchestrator sends the task to the target NPC (e.g., `corca`)
+2. The target NPC works on the task using their available jinxs
+3. The orchestrator **reviews** the output and decides: COMPLETE or needs more work
+4. If incomplete, the orchestrator provides feedback and the target NPC iterates
+5. This continues until complete or max iterations reached
+
+```
+┌─────────────────┐     task      ┌─────────────────┐
+│   Orchestrator  │ ────────────▶ │   Target NPC    │
+│    (sibiji)     │               │    (corca)      │
+│                 │ ◀──────────── │                 │
+│   Reviews work  │    output     │  Uses jinxs:    │
+│   Gives feedback│               │  - python       │
+└─────────────────┘               │  - sh           │
+        │                         │  - edit_file    │
+        │ feedback                └─────────────────┘
+        ▼
+   Iterate until
+   task complete
+```
+
+## Convening Multi-NPC Discussions
+
+The `/convene` jinx brings multiple NPCs together for a structured discussion:
+
+```bash
+/convene "How should we architect the new API?" --npcs corca,guac,frederic --rounds 3
+```
+
+**How it works:**
+1. Each NPC contributes their perspective based on their persona
+2. NPCs respond to each other, building on or challenging ideas
+3. Random follow-ups create organic discussion flow
+4. After all rounds, the orchestrator synthesizes key points
+
+```
+Round 1:
+  [corca]: "From a code structure perspective..."
+    [guac responds]: "I agree, but we should also consider..."
+    [frederic]: "The mathematical elegance here suggests..."
+
+Round 2:
+  [guac]: "Building on what corca said..."
+    [corca responds]: "That's a good point about..."
+
+SYNTHESIS:
+  - Key agreements: ...
+  - Areas of disagreement: ...
+  - Recommended next steps: ...
+```
+
+## Visualizing Team Structure
+
+Use `/teamviz` to see how your NPCs and jinxs are connected:
+
+```bash
+/teamviz save=team_structure.png
+```
+
+This generates two views:
+- **Network view**: Organic layout showing NPC-jinx relationships
+- **Ordered view**: NPCs on left, jinxs grouped by category on right
+
+Shared jinxs (like `python` used by 7 NPCs) appear with thicker connection bundles, helping you identify common capabilities and potential consolidation opportunities.
+
+# NQL - SQL Models with AI Functions
+
+NQL (NPC Query Language) enables AI-powered data transformations directly in SQL, similar to dbt but with embedded LLM calls. Create `.sql` files in `npc_team/models/` that combine standard SQL with `nql.*` AI function calls, then run them on a schedule to build analytical tables enriched with AI insights.
+
+## How It Works
+
+NQL models are SQL files with embedded AI function calls. When executed:
+
+1. **Model Discovery**: The compiler finds all `.sql` files in your `models/` directory
+2. **Dependency Resolution**: Models referencing other models via `{{ ref('model_name') }}` are sorted topologically
+3. **Jinja Processing**: Template expressions (`{% %}`) are evaluated with access to NPC/team/jinx context
+4. **Execution Path**:
+   - **Native AI databases** (Snowflake, Databricks, BigQuery): NQL calls are translated to native AI functions (e.g., `SNOWFLAKE.CORTEX.COMPLETE()`)
+   - **Standard databases** (SQLite, PostgreSQL, etc.): SQL executes first, then Python-based AI functions process each row
+5. **Materialization**: Results are written back to the database as tables or views
+
+## Example Model
+
+```sql
+{{ config(materialized='table') }}
+
+SELECT
+    command,
+    count(*) as exec_count,
+    nql.synthesize(
+        'Analyze "{command}" usage pattern with {exec_count} executions',
+        'sibiji',
+        'pattern_insight'
+    ) as insight
+FROM command_history
+GROUP BY command
+```
+
+The `nql.synthesize()` call:
+- Takes a prompt template with `{column}` placeholders filled from each row
+- Uses the specified NPC (`sibiji`) for context and model/provider settings
+- Returns the AI response as a new column (`insight`)
+
+## Enterprise Database Support
+
+NQL **automatically translates** your `nql.*` function calls to native database AI functions under the hood. You write portable NQL syntax once, and the compiler handles the translation:
+
+| Database | Auto-Translation | Your Code → Native SQL |
+|----------|------------------|------------------------|
+| **Snowflake** | Cortex AI | `nql.synthesize(...)` → `SNOWFLAKE.CORTEX.COMPLETE('llama3.1-8b', ...)` |
+| **Databricks** | ML Serving | `nql.generate_text(...)` → `ai_query('databricks-meta-llama...', ...)` |
+| **BigQuery** | Vertex AI | `nql.summarize(...)` → `ML.GENERATE_TEXT(MODEL 'gemini-pro', ...)` |
+| **SQLite/PostgreSQL** | Python Fallback | SQL executes first, then AI applied row-by-row via `npcpy` |
+
+Write models locally with SQLite, deploy to Snowflake/Databricks/BigQuery with zero code changes—the NQL compiler rewrites your AI calls to use native accelerated functions automatically.
+
+## NQL Functions
+
+**Built-in LLM functions** (from `npcpy.llm_funcs`):
+- `nql.synthesize(prompt, npc, alias)` - Synthesize insights from multiple perspectives
+- `nql.summarize(text, npc, alias)` - Summarize text content
+- `nql.criticize(text, npc, alias)` - Provide critical analysis
+- `nql.extract_entities(text, npc, alias)` - Extract named entities
+- `nql.generate_text(prompt, npc, alias)` - General text generation
+- `nql.translate(text, npc, alias)` - Translate between languages
+
+**Team jinxs as functions**: Any jinx in your team can be called as `nql.<jinx_name>(...)`:
+```sql
+nql.sample('Generate variations of: {text}', 'frederic', 'variations')
+```
+
+**Model references**: Use `{{ ref('other_model') }}` to create dependencies between models. The compiler ensures models run in the correct order.
+
+## Jinja Templating
+
+NQL models support Jinja expressions (using `{% %}` delimiters) for dynamic access to NPC and team properties:
+
+```sql
+-- Use the team's forenpc dynamically
+nql.synthesize('Analyze this...', '{% team.forenpc %}', 'result')
+
+-- Access NPC properties
+-- Model: {% npc('sibiji').model %}
+-- Provider: {% npc('corca').provider %}
+-- Directive: {% npc('frederic').directive %}
+
+-- Access jinx metadata
+-- Description: {% jinx('sample').description %}
+
+-- Environment variables with defaults
+-- API URL: {% env('NPCSH_API_URL', 'http://localhost:5337') %}
+```
+
+## Running Models
+
+```bash
+# List available models (shows [NQL] tag for models with AI functions)
+nql show=1
+
+# Run all models in dependency order
+nql
+
+# Run a specific model
+nql model=daily_summary
+
+# Use a different database
+nql db=~/analytics.db
+
+# Specify output schema
+nql schema=analytics
+
+# Schedule with cron (runs daily at 6am)
+nql install_cron="0 6 * * *"
+```
+
+## Example: Analytics Pipeline
+
+```
+models/
+├── base/
+│   ├── command_stats.sql      # Pure SQL aggregations
+│   └── daily_activity.sql     # Time-series breakdown
+└── insights/
+    ├── command_patterns.sql   # Uses nql.synthesize() on base stats
+    └── weekly_summary.sql     # References command_patterns via {{ ref() }}
+```
+
+Run `nql` to execute the entire pipeline—base models first, then insights that depend on them.
+
+# Working with NPCs (Agents)
+
+NPCs are AI agents with distinct personas, models, and tool sets. You can interact with them in two ways:
+
+## Switching to an NPC
+
+Use `/npc <name>` or `/n <name>` to switch your session to a different NPC. All subsequent messages will be handled by that NPC until you switch again:
+
+```bash
+/npc corca          # Switch to corca for coding tasks
+/n frederic         # Switch to frederic for math/music
+```
+
+You can also invoke an NPC directly as a slash command to switch to them:
+```bash
+/corca              # Same as /npc corca
+/guac               # Same as /npc guac
+```
+
+## One-Time Questions with @
+
+Use `@<npc_name>` to ask a specific NPC a one-time question without switching your session:
+
+```bash
+@corca can you review this function for bugs?
+@frederic what's the derivative of x^3 * sin(x)?
+@alicanto search for recent papers on transformer architectures
+```
+
+The NPC responds using their persona and available jinxs, then control returns to your current NPC.
+
+## Available NPCs
+
+| NPC | Specialty | Key Jinxs |
+|-----|-----------|-----------|
+| `sibiji` | Orchestrator/coordinator | delegate, convene, search |
+| `corca` | Coding and development | python, sh, edit_file, search |
+| `plonk` | Browser/GUI automation | browser_action, screenshot, click |
+| `alicanto` | Research and analysis | arxiv, semantic_scholar, paper_search |
+| `frederic` | Math, physics, music | python, vixynt, roll, sample, wander |
+| `guac` | General assistant | python, sh, search |
+| `kadiefa` | Creative generation | vixynt, roll, wander |
+
+# Jinxs (Macros/Tools)
+
+Jinxs are reusable tools that NPCs can invoke. They're activated with `/<jinx_name> ...` in npcsh or via the `npc` CLI in bash. For converting any `/<command>` in npcsh to bash, replace `/` with `npc `:
+
+```bash
+# In npcsh:
+/vixynt "a sunset over mountains"
+
+# In bash:
+npc vixynt "a sunset over mountains"
+```
+
+## Jinx Commands
+
+### Orchestration & Research
+| Command | Description |
+|---------|-------------|
+| `/alicanto` | Deep research with multiple perspectives. Usage: `/alicanto 'query' --num-npcs 3 --depth 2` |
+| `/convene` | Multi-NPC structured discussion. Usage: `/convene "topic" --npcs corca,guac --rounds 3` |
+| `/delegate` | Delegate task to NPC with review loop. Usage: `/delegate npc_name=corca task="..." max_iterations=5` |
+| `/search` | Web/memory/knowledge graph search. Usage: `/search 'query' --sprovider perplexity` |
+
+### Generation
+| Command | Description |
+|---------|-------------|
+| `/vixynt` | Generate/edit images. Usage: `/vixynt 'description' --igmodel gpt-image-1 --igprovider openai` |
+| `/roll` | Generate videos. Usage: `/roll 'description' --vgmodel veo-3.1-fast-generate-preview --vgprovider gemini` |
+| `/sample` | Context-free LLM prompt. Usage: `/sample 'question' -m gpt-4o-mini --temp 0.7` |
+
+### Modes & Sessions
+| Command | Description |
+|---------|-------------|
+| `/spool` | Interactive chat with fresh context/RAG. Usage: `/spool --attachments 'file1,file2' -n corca` |
+| `/yap` | Voice chat mode. Usage: `/yap -n frederic` |
+| `/pti` | Pardon-the-interruption reasoning mode. Usage: `/pti` |
+| `/plonk` | GUI automation with vision. Usage: `/plonk 'click the submit button'` |
+| `/wander` | Exploratory thinking with temperature shifts. Usage: `/wander 'query' --model deepseek-r1:32b` |
+
+### Data & Analytics
+| Command | Description |
+|---------|-------------|
+| `/nql` | Run NQL SQL models. Usage: `/nql show=1`, `/nql model=daily_summary` |
+| `/teamviz` | Visualize team structure. Usage: `/teamviz save=output.png` |
+| `/ots` | Screenshot analysis. Usage: `/ots` then select area |
+| `/sleep` | Evolve knowledge graph. Usage: `/sleep --ops link_facts,deepen` |
+
+### System & Config
+| Command | Description |
+|---------|-------------|
+| `/build` | Build team to deployable format. Usage: `/build docker --output ./deploy` |
+| `/serve` | Full agentic server with NPC management, jinx controls, and OpenAI-compatible endpoints. Usage: `/serve --port 5337` |
+| `/compile` | Compile NPC profiles. Usage: `/compile path/to/npc` |
+| `/init` | Initialize NPC project. Usage: `/init` |
+| `/set` | Set config values. Usage: `/set model gemma3:4b`, `/set provider ollama` |
+| `/help` | Show help. Usage: `/help` |
+| `/jinxs` | List available jinxs. Usage: `/jinxs` |
+| `/npc-studio` | Launch NPC Studio GUI. Usage: `/npc-studio` |
+| `/trigger` | Set up system triggers. Usage: `/trigger 'description' -m gemma3:27b` |
     
     ## Common Command-Line Flags:
     
@@ -294,7 +622,6 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     --exploration     (-ex)        | --npc             (-np)        | --rprovider       (-rp)        |                               
     --format          (-f)         | --num_frames      (-num_f)     | --sprovider       (-s)         |                               
     ```
-    '
 
 ## Read the Docs
 To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
@@ -489,27 +816,41 @@ export PERPLEXITY_API_KEY='your_perplexity_key'
  Once initialized and set up, you will find the following in your `~/.npcsh` directory:
 ```bash
 ~/.npcsh/
-├── npc_team/           # Global NPCs
-│   ├── jinxs/          # Global tools
-│   └── assembly_lines/ # Workflow pipelines
-│   └── sibiji.npc  # globally available npc 
-│   └── npcsh.ctx  # global context file
-
-
-
+├── npc_team/              # Global NPC team
+│   ├── jinxs/
+│   │   ├── bin/           # CLI commands (wander, spool, yap, nql, vixynt, roll, sample)
+│   │   └── lib/           # Library jinxs by category
+│   │       ├── core/      # python, sh, sql, search, edit_file, load_file
+│   │       ├── browser/   # browser_action, screenshot
+│   │       ├── orchestration/  # delegate, convene
+│   │       └── research/  # arxiv, semantic_scholar, paper_search
+│   ├── models/            # NQL SQL models
+│   ├── assembly_lines/    # Workflow pipelines
+│   ├── sibiji.npc         # Orchestrator NPC
+│   ├── corca.npc          # Coding specialist
+│   ├── plonk.npc          # Browser automation
+│   ├── ...                # Other NPCs
+│   └── npcsh.ctx          # Team context (sets forenpc, team name)
 ```
 For cases where you wish to set up a project specific set of NPCs, jinxs, and assembly lines, add a `npc_team` directory to your project and `npcsh` should be able to pick up on its presence, like so:
 ```bash
 ./npc_team/            # Project-specific NPCs
-├── jinxs/             # Project jinxs #example jinx next
-│   └── example.jinx
-└── assembly_lines/    # Agentic Workflows
-    └── example.line
-└── models/    # Project workflows
-    └── example.model
-└── example1.npc        # Example NPC
-└── example2.npc        # Example NPC
-└── team.ctx            # Example ctx
+├── jinxs/             # Project jinxs
+│   ├── bin/           # Standalone CLI commands (unique names, auto-registered)
+│   │   └── wander, spool, yap, nql, vixynt, roll, sample
+│   └── lib/           # Library jinxs organized by category
+│       ├── core/      # Core utilities (python, sh, sql, search, etc.)
+│       ├── browser/   # Browser automation
+│       ├── orchestration/  # delegate, convene
+│       └── research/  # Research tools (arxiv, semantic_scholar)
+├── models/            # NQL SQL models for AI-powered data pipelines
+│   ├── base/          # Base statistics models
+│   └── insights/      # Models with nql.* AI functions
+├── assembly_lines/    # Agentic Workflows
+│   └── example.line
+├── example1.npc       # Example NPC
+├── example2.npc       # Example NPC
+└── team.ctx           # Team context file
 
 
 ```