feat: onboard docs, agent instructions, and RAG configuration

AGENTS.md

@@ -0,0 +1,24 @@
+# Agent Guidelines for DOC-KB-RAG
+
+## Repository Focus
+This repository contains a RAG (Retrieval-Augmented Generation) agent that reads Markdown/JSON manuals and provides AI-powered answers. The documentation it reads is completely **interchangeable**. 
+
+As an AI Agent working entirely within this codebase, you must adhere strictly to the following rules:
+
+## General Rules
+1. **Scope:** Your primary scope is the Python RAG implementation (`ingest.py` and `query.py`), the local Supabase integration, and the Gemini configuration. Do not build tangential functionality outside the RAG scope unless explicitly told.
+2. **Modularity:** The scripts default to Gemini and Supabase, but architect any new changes so the data layer (Vector DB) and reasoning layer (LLM) remain loosely coupled and pluggable.
+
+## CLI and Execution
+1. **Virtual Environment First:** All Python scripts must execute within the `venv`. Never install global pip packages. 
+2. **Docker Dependency:** Before executing any Supabase node scripts (`npx supabase...`), verify that Docker Desktop is running, as it is a strict dependency for the local Postgres Vector instance.
+3. **Execution Verification:** Before proposing that a feature is complete, use the `run_command` tools to verify your changes by literally running `python query.py "<Test Question>"` to ensure the RAG pipeline is unbroken.
+
+## Safety & Boundaries
+1. **No Destructive Migrations:** Never delete, drop, or permanently alter the Vector Database schemas using Supabase commands or raw SQL without explicit, confirming approval from the user.
+2. **Git Hygiene:** Suggest clear, concise Git commits, but do not automatically push, force-push, rebase, or delete branches without asking.
+3. **Secret Management:** Never log, print, or commit `GOOGLE_API_KEY` or `DB_CONNECTION_STRING` anywhere. 
+
+## Documentation
+1. Keep the `README.md` as the definitive source of truth for onboarding users. If you change a fundamentally required script argument, update the README immediately.
+2. Treat `DOCS_PATH` as an agnostic source. The user can inject *any* repository's documentation into this engine. Ensure your code does not blindly assume content layout or structure.

README.md

@@ -1,74 +1,140 @@
-# Openclaw RAG System - Usage Guide
+# DOC-KB-RAG
+
+Retrieval-Augmented Generation for interchangeable documentation sets. This
+repository keeps the RAG application, the local Supabase setup, and a sample
+documentation corpus in one place.
+
+## What Lives Here
+
+- `rag-agent/` contains the runnable RAG app.
+- `docs/` is the documentation corpus currently being indexed.
+- Root-level files such as `AGENTS.md`, `GEMINI.md`, and `CHANGELOG.md` are
+  project guidance and reference material.
+
+## Structure Map
+
+```text
+DOC-KB-RAG/
+|-- AGENTS.md                # Local agent instructions for this repo
+|-- CHANGELOG.md             # Imported/source project changelog
+|-- GEMINI.md                # Gemini-specific project context
+|-- LICENSE
+|-- README.md
+|-- docs/                    # Documentation corpus to ingest (replaceable)
+|   |-- index.md
+|   |-- start/
+|   |-- concepts/
+|   |-- tools/
+|   |-- providers/
+|   `-- ...many topic folders
+`-- rag-agent/               # RAG application workspace
+    |-- .env                 # Local secrets/config (gitignored)
+    |-- ingest.py            # Ingest docs into the vector store
+    |-- query.py             # Query the indexed docs
+    |-- tools/               # One-off helper scripts
+    |   |-- README.md
+    |   |-- check_dim.py
+    |   |-- list_llm_models.py
+    |   `-- list_models.py
+    |-- supabase/            # Local Supabase project files
+    |-- venv/                # Python virtual environment
+    |-- package.json         # Supabase CLI dependency
+    `-- package-lock.json
+```
+
+## Working Directory Rules
 
-This system allows you to perform Retrieval-Augmented Generation (RAG) queries against the Openclaw Gateway documentation using Google Gemini and a local Supabase vector database.
+Run the Python and Supabase commands from `rag-agent/`. That directory is the
+application root and contains the local `.env`, `venv`, and Supabase config.
 
-## 🚀 Quick Start
+## Quick Start
 
 ### 1. Prerequisites
-- **Python 3.10+**
-- **Docker Desktop** (Must be running)
-- **Node.js** (For Supabase CLI)
 
-### 2. Activate the Environment
-Open a terminal in `C:\Users\johan\Openclaw Gateway\rag-agent` and run:
+- Python 3.10+
+- Docker Desktop running
+- Node.js
+
+### 2. Activate the virtual environment
+
+From `rag-agent/`:
+
+**On Linux/macOS:**
+
+```bash
+source venv/bin/activate
+```
+
+**On Windows (Git Bash):**
+
+```bash
+source venv/Scripts/activate
+```
+
+**On Windows (PowerShell):**
+
 ```powershell
 .\venv\Scripts\Activate.ps1
 ```
 
-### 3. Ensure the Database is Running
-The system uses a local Supabase instance. If it's not running, start it:
-```powershell
+### 3. Start local Supabase
+
+```bash
 npx supabase start
 ```
 
----
+## Configuration
 
-## 🔍 How to Query
-To ask a question about the Openclaw Gateway documentation, use the `query.py` script:
+Set these values in `rag-agent/.env`:
 
-```powershell
-python query.py "What is the command to onboard a new user?"
-```
+- `GOOGLE_API_KEY`: Gemini API key
+- `DB_CONNECTION_STRING`: local Postgres connection string
+- `DOCS_PATH`: directory to ingest
 
-The script will:
-1. Search the local Supabase DB for relevant context.
-2. Send that context to Gemini 3.1 Flash Lite Preview.
-3. Provide a synthesized answer based on your files.
+`DOCS_PATH` is intentionally agnostic. It can point to this repository's
+`docs/` folder or to any other Markdown/JSON documentation source.
 
----
+## Main Commands
 
-## 📥 How to Ingest (Update Data)
-If you add new Markdown or JSON files to the `Openclaw Gateway` folder, you need to re-index them:
+From `rag-agent/`:
 
-```powershell
+Ingest the configured documentation set:
+
+```bash
 python ingest.py
 ```
-*Note: This script uses the `gemini-embedding-2-preview` model with 3,072 dimensions for high accuracy.*
 
----
+Query the indexed documentation:
+
+```bash
+python query.py "What is the command to onboard a new user?"
+```
+
+Optional helper scripts:
 
-## ⚙️ Configuration
-The configuration is stored in the `.env` file:
-- `GOOGLE_API_KEY`: Your Gemini API key.
-- `DB_CONNECTION_STRING`: Local Postgres URI.
-- `DOCS_PATH`: The source folder for your documentation.
+```bash
+python tools/list_models.py
+python tools/list_llm_models.py
+python tools/check_dim.py
+```
 
----
+## Maintenance
 
-## 🛠️ Maintenance & Troubleshooting
+Stop Supabase when you are done:
 
-### Stopping the Database
-To save system resources when not using the RAG agent:
-```powershell
+```bash
 npx supabase stop
 ```
 
-### Resetting the Database
-If you ever want to wipe the index and start fresh:
-1. Stop Supabase: `npx supabase stop`
-2. Start Supabase: `npx supabase start`
-3. Run ingestion: `python ingest.py`
+If the corpus changes, rerun:
+
+```bash
+python ingest.py
+```
+
+## Notes
 
-### Common Errors
-- **403 Forbidden**: Ensure the "Generative Language API" is enabled in your Google Cloud Project.
-- **Docker Connection Error**: Ensure Docker Desktop is running and you are in the correct context (`docker context use default`).
+- Keep `ingest.py` and `query.py` at the top of `rag-agent/`; CI and local
+  usage depend on those entrypoints.
+- Avoid moving `rag-agent/venv/` or `rag-agent/supabase/` unless you are also
+  rebuilding the environment and command assumptions around them.

docs/.i18n/README.md

@@ -0,0 +1,31 @@
+# OpenClaw docs i18n assets
+
+This folder stores **generated** and **config** files for documentation translations.
+
+## Files
+
+- `glossary.<lang>.json` — preferred term mappings (used in prompt guidance).
+- `<lang>.tm.jsonl` — translation memory (cache) keyed by workflow + model + text hash.
+
+## Glossary format
+
+`glossary.<lang>.json` is an array of entries:
+
+```json
+{
+  "source": "troubleshooting",
+  "target": "故障排除",
+  "ignore_case": true,
+  "whole_word": false
+}
+```
+
+Fields:
+
+- `source`: English (or source) phrase to prefer.
+- `target`: preferred translation output.
+
+## Notes
+
+- Glossary entries are passed to the model as **prompt guidance** (no deterministic rewrites).
+- The translation memory is updated by `scripts/docs-i18n`.

docs/.i18n/glossary.ja-JP.json

@@ -0,0 +1,14 @@
+[
+  { "source": "OpenClaw", "target": "OpenClaw" },
+  { "source": "Gateway", "target": "Gateway" },
+  { "source": "Pi", "target": "Pi" },
+  { "source": "Skills", "target": "Skills" },
+  { "source": "local loopback", "target": "local loopback" },
+  { "source": "Tailscale", "target": "Tailscale" },
+  { "source": "Getting Started", "target": "はじめに" },
+  { "source": "Getting started", "target": "はじめに" },
+  { "source": "Quick start", "target": "クイックスタート" },
+  { "source": "Quick Start", "target": "クイックスタート" },
+  { "source": "Onboarding", "target": "オンボーディング" },
+  { "source": "wizard", "target": "ウィザード" }
+]