@webship.co/workspace-rag 0.0.0-stage → 1.0.0-beta1

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @webship.co/workspace-rag
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **RAG** workspace of the [Webship Workspace](https://github.com/webship/workspace) dashboard:
+the `rag/` folder (type `sites`), its settings file (`core/config/workspace.rag.settings.yml`),
+its commands and its docs, as a plugin.
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-rag
+bash core/scripts/plugins.sh --activate rag     # puts `rag` on the workspaces list of settings.yml
+bash core/scripts/plugins.sh --install rag      # the folder, its settings file (once), its commands, its docs (once)
+```
+
+The settings file and the docs are placed once and never overwritten: they hold what you put there.
+`--deactivate` takes the workspace off the list; the folder and its content stay.
+
+## The commands
+
+| Command |
+| --- |
+| `cmd-milvus-backup.sh` |
+| `cmd-milvus-mcp.sh` |
+| `cmd-milvus-project.sh` |
+| `cmd-tools-rag.sh` |
+| `cmd-tools-reclaim.sh` |
+
+The bash functions these commands call live in the dashboard's `core/scripts/functions`.

package/commands/cmd-milvus-backup.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# workspace-name: Milvus (backup)
+
+# Archive a Milvus instance: the etcd metadata, the MinIO segments and the data directory, plus a
+# JSON manifest of its collections. All three volumes together — a dump of any one of them
+# restores nothing.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.rag.settings.yml);
+
+ARGPARSE_DESCRIPTION="Back up a Milvus instance — its metadata, its segments and its collection manifest"
+source ${WORKSPACE_SCRIPTS}/args/arg-milvus-backup.sh || exit 1 ;
+
+shift $#;
+
+milvus_backup ;

package/commands/cmd-milvus-mcp.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+# workspace-name: Milvus (mcp)
+
+# Give the Milvus database to the Claude Code CLI over MCP — one registration covers every
+# collection in it, because the server's tools list and search the whole database.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings — the MCP package and the instance defaults live in the milvus: block.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.rag.settings.yml);
+
+ARGPARSE_DESCRIPTION="Register, unregister or run the Milvus MCP server for the Claude Code CLI"
+source ${WORKSPACE_SCRIPTS}/args/arg-milvus-mcp.sh || exit 1 ;
+
+shift $#;
+
+milvus_mcp ;

package/commands/cmd-milvus-project.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# workspace-name: Milvus (vector database for RAG)
+
+# Run Milvus self-hosted inside DDEV, in the rag workspace.
+# One command for the whole standalone stack: the DDEV project, the Milvus + etcd + MinIO compose
+# services, the Attu web UI, and the nginx reverse proxy that puts all of it on one https origin.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings — every default this command uses lives in the milvus: block there.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.rag.settings.yml);
+
+ARGPARSE_DESCRIPTION="Run Milvus self-hosted in DDEV, with the Attu UI and a published gRPC port for pymilvus and MCP"
+source ${WORKSPACE_SCRIPTS}/args/arg-milvus.sh || exit 1 ;
+
+shift $#;
+
+build_milvus ;

package/commands/cmd-tools-rag.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# workspace-name: RAG indexes (list, search, serve over MCP)
+
+# Work with the project RAG indexes held in the Milvus instance of this workspace.
+# The indexes are BUILT from each project's own workspace folder:
+#   cd ~/workspace/<workspace> && bash cmd-tools-ragify.sh <project>
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.rag.settings.yml);
+
+ARGPARSE_DESCRIPTION="List, describe, search and remove the project RAG indexes in ~/workspace/rag"
+source ${WORKSPACE_SCRIPTS}/args/arg-rag.sh || exit 1 ;
+
+shift $#;
+
+rag_command ;

package/commands/cmd-tools-reclaim.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# Reclaim the disk that REMOVED projects left behind — their DDEV databases, snapshots, built images
+# and containers. A project whose folder is still on disk is never touched, stopped or not.
+#
+# The sweep is machine-wide wherever you run it: it takes no project name, reads WORKSPACE_ROOT, and
+# protects every project folder in the tree — so this copy behaves identically to the one in any other
+# workspace. It ships in each workspace that leans on DDEV, graphify or RAG for the same reason
+# cmd-tools-graphify.sh does: the folder you are standing in is where you look for a cmd-tools-*.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings and extra lists.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.rag.settings.yml);
+
+ARGPARSE_DESCRIPTION="Reclaim disk from projects that no longer have a folder — dry run unless --apply"
+source ${WORKSPACE_SCRIPTS}/args/arg-reclaim.sh || exit 1 ;
+
+shift $#;
+
+reclaim_command ;

package/config/workspace.rag.settings.yml

@@ -0,0 +1,90 @@
+doc:
+  name: rag
+
+# RAG both builds and holds: a Milvus vector database is a DDEV project (so the page needs the
+# project table, the Build form and the DDEV actions), and the per-project index manifests written
+# by cmd-tools-ragify.sh sit beside it as files.
+#
+# What this workspace is FOR, next to graphs/: graphify parses code deterministically and answers
+# "what depends on what". It reads no Markdown, no Twig, no *.module hooks and none of the Drupal
+# wiring YAML. A RAG index reads exactly those — the prose, the templates, the config — and answers
+# "where is this explained / configured / worded". They are complements, not alternatives.
+presentation:
+  icon: tabler:database-search
+  # The folder is `rag`; the dashboard card says RAG, because that is what it is called —
+  # `label` is the presentational name and never the directory.
+  label: RAG
+  subtitle: Milvus Vector Databases & Project RAG Indexes
+  noun: instance
+  kind: projects
+  also_files: true
+
+# Milvus, self-hosted in DDEV (rag/cmd-milvus-project.sh).
+# These are the DEFAULTS for that command; every one is overridable per run by the matching
+# argument, so a one-off instance needs no settings edit.
+milvus:
+  # Default project name, and so the hostname:
+  #   bash cmd-milvus-project.sh milvus
+  # gives https://milvus.rag.workspace.ddev.site (Attu, the web UI) and the canonical
+  # https://milvus.ddev.site. More than one instance is fine — each gets its own etcd, object
+  # store and gRPC port.
+  project: milvus
+  # Milvus image tag. 2.6.x is the mature line; its standalone mode needs etcd (metadata) and
+  # MinIO (segments) and uses the built-in Woodpecker WAL, so no Pulsar or Kafka.
+  # v3.0.0 was released 2026-07-29 — new enough that the default stays on 2.6 until it has run
+  # here for a while. Override per run with --milvus-version.
+  version: "v2.6.21"
+  # Attu, the Milvus web UI (https://github.com/zilliztech/attu). The 3.0.0 tags are betas, so
+  # the default is the newest stable 2.6 line.
+  attu_version: "v2.6.5"
+  # The gRPC/REST port Milvus is published on, on the HOST. The DDEV router serves HTTP(S) only,
+  # so a client outside the project's network — pymilvus on this machine, the MCP server, a
+  # notebook — reaches Milvus on 127.0.0.1:<this>. Taken as the first free port from here up, so
+  # a second instance does not fail to start.
+  grpc_port: 19530
+  # Which hostname Attu is served on: `hub` is <project>.rag.workspace.ddev.site, `canonical` is
+  # <project>.ddev.site, anything else is used verbatim.
+  public_uri: hub
+  # Milvus authentication. Off by default: this is a local development database on a DDEV
+  # network, and every tool here would otherwise need the credential threaded through it. Set
+  # `authorization: true` and Milvus enforces its default root:Milvus login (change the password
+  # inside Milvus after the first start).
+  authorization: false
+  token: CHANGE_ME
+  # The Milvus MCP server (rag/cmd-milvus-mcp.sh) — what gives the Claude Code CLI its
+  # milvus_* tools. PyPI ships it under pre-release version numbers only, so the pin carries the
+  # .devN suffix; uvx refuses a bare `mcp-server-milvus` without one.
+  mcp:
+    package: "mcp-server-milvus==0.1.1.dev9"
+
+# How cmd-tools-ragify.sh indexes a project into that database.
+rag:
+  # Collection naming: <prefix>_<workspace>_<project>, non-alphanumerics folded to _ because
+  # Milvus collection names allow letters, digits and underscore only.
+  collection_prefix: ws
+  # Retrieval mode.
+  #   bm25   — Milvus's built-in BM25 function builds the sparse vectors inside the database.
+  #            No model, no API key, nothing leaves this machine. THE DEFAULT.
+  #   openai — additionally embeds each chunk with the OpenAI API (the key in settings.yml) and
+  #            searches dense + sparse together. Better on paraphrase; it does send every indexed
+  #            chunk to OpenAI, so it is opt-in per run (--embedding openai).
+  embedding: bm25
+  openai_model: text-embedding-3-small
+  # Chunking. Lines rather than tokens: a code chunk that keeps whole lines is one you can open
+  # at the reported line number, and the overlap keeps a function that straddles a boundary
+  # findable from either side.
+  chunk_lines: 60
+  chunk_overlap: 10
+  # Files larger than this are skipped — a 4 MB minified library is not prose worth retrieving.
+  max_file_kb: 512
+
+# What this folder's projects are, and which actions their rows offer:
+# sites | code | files | media | ai-items — see core/workspace-app/WORKSPACES.md.
+type: sites
+
+# What the assistant is called on THIS workspace's page, and what its composer says when empty.
+# `default` in either means "whatever settings.yml says" — the global value, so a rename there
+# still reaches this page. Set a value here to override it for this workspace alone.
+assistant:
+  name: default
+  placeholder: default

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The RAG workspace for Webship Workspace: the `rag/` folder as a plugin.
+ *
+ * What the package carries is placed by the installer from the manifest (the folder's settings file,
+ * its commands and its docs) and listed by --activate; the dashboard draws the workspace from the
+ * settings file like any other. Nothing to register at run time yet: this is where the folder's own
+ * rail buttons, row menus or assistant context would go.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+export declare const WORKSPACE_KEY = "rag";
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The RAG workspace for Webship Workspace: the `rag/` folder as a plugin.
+ *
+ * What the package carries is placed by the installer from the manifest (the folder's settings file,
+ * its commands and its docs) and listed by --activate; the dashboard draws the workspace from the
+ * settings file like any other. Nothing to register at run time yet: this is where the folder's own
+ * rail buttons, row menus or assistant context would go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_KEY = void 0;
+exports.register = register;
+exports.WORKSPACE_KEY = 'rag';
+function register(api) {
+    api.addAssistantContext(() => `The rag/ workspace is the RAG workspace (a plugin, @webship.co/workspace-rag); its commands are the cmd-*.sh scripts in that folder.`);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAMH,4BAEC;AAJY,QAAA,aAAa,GAAG,KAAK,CAAC;AAEnC,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,sIAAsI,CAAC,CAAC;AACxK,CAAC"}

package/docs/AGENTS.md

@@ -0,0 +1,47 @@
+# RAG
+
+The Milvus vector database, and the per-project RAG indexes held in it.
+
+Part of the **Webship Workspace** (`~/workspace`), a DDEV-only harness. The rules in the root
+`CLAUDE.md` apply here too; what follows is what is specific to this folder.
+
+## What lives here
+
+A Milvus instance is a DDEV project like any other — start and stop it from its row. The indexes
+themselves live inside Milvus, not on disk; `bindings.yml` records which instance holds which
+project's index.
+
+**Index a project from its own workspace, never from here:**
+
+```bash
+cd ~/workspace/dev && bash cmd-tools-ragify.sh <project>
+```
+
+Retrieval is BM25 by default: the database builds the vectors itself, so no model runs and nothing
+leaves this machine.
+
+## The rule that matters here
+
+Everything goes through DDEV. Never a host `composer`, `drush` or `mysql`:
+
+```bash
+ddev composer require drupal/something
+ddev drush cr
+ddev export-db --file=…        # not mysqldump
+ddev delete -y -O              # not a dropped database
+```
+
+`ddev start` takes `-y`; **`ddev stop` does not**. Never write a `$databases` block into
+`settings.php` — DDEV's `settings.ddev.php` owns the connection.
+
+## Commands here
+
+```bash
+bash cmd-milvus-backup.sh                             # Milvus (backup)
+bash cmd-milvus-mcp.sh                                # Milvus (mcp)
+bash cmd-milvus-project.sh                            # Milvus (vector database for RAG)
+bash cmd-tools-rag.sh                                 # RAG indexes (list, search, serve over MCP)
+```
+
+Every one locates the workspace from its own path, so there is nothing to export and nothing to
+install. `--help` on any of them lists its arguments.

package/docs/CLAUDE.md

@@ -0,0 +1,7 @@
+# RAG — workspace context
+
+You are inside the **rag** workspace of the Webship Workspace (`~/workspace`).
+
+@AGENTS.md
+
+The rules in it apply to everything under this folder, however deep.

package/docs/README.md

@@ -0,0 +1,10 @@
+# RAG
+
+Vector databases and the per-project indexes built against them.
+
+An instance is a DDEV project, so it is built and managed from the dashboard page like any other;
+the index manifests sit beside it as files.
+
+What this is for, next to `graphs/`: a graph parses code and answers *what depends on what*. It
+reads no Markdown, no Twig and none of the Drupal wiring YAML. A RAG index reads exactly those —
+the prose, the templates, the configuration — and answers *where is this explained or configured*.

package/features/rag.feature

@@ -0,0 +1,13 @@
+Feature: The RAG workspace plugin
+  Once the plugin is activated and installed, the rag workspace is on the dashboard, and the
+  Plugins page lists the plugin with its four steps.
+
+  Scenario: The workspace page is there
+    Given I am on "/rag"
+     Then the element "h1" should be displayed
+      And the element "#webship-workspace-projects, .items-list, .workspace-page" should be attached
+
+  Scenario: The plugin is listed on the Plugins page
+    Given I am on "/settings/plugins"
+     Then I should see "RAG"
+      And I should see "@webship.co/workspace-rag"

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@webship.co/workspace-rag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta1",
+  "description": "The RAG workspace for Webship Workspace: the `rag/` folder (type sites), its settings file, its 5 commands and its docs, activated as a plugin.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webship/workspace-rag.git"
+  },
+  "files": [
+    "dist/src",
+    "commands",
+    "config",
+    "docs",
+    "features",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "workspacePlugin": {
+    "name": "rag",
+    "label": "RAG",
+    "workspace": {
+      "key": "rag",
+      "settingsTemplate": "config/workspace.rag.settings.yml",
+      "files": [
+        "commands/cmd-milvus-backup.sh",
+        "commands/cmd-milvus-mcp.sh",
+        "commands/cmd-milvus-project.sh",
+        "commands/cmd-tools-rag.sh",
+        "commands/cmd-tools-reclaim.sh"
+      ],
+      "docs": [
+        "docs/AGENTS.md",
+        "docs/CLAUDE.md",
+        "docs/README.md"
+      ]
+    },
+    "features": [
+      "features/rag.feature"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@webship.co/workspace-plugin-api": "^1.0.0-beta1",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}