@ericrisco/rsc 3.7.4 → 4.0.0

package/skills/connect-tool/references/database-bridge.md

@@ -0,0 +1,159 @@
+# Database bridge: reading an installed program, read-only
+
+Goal: the agent **reads** the data of a desktop or office program (SQL Server or Access) **without
+being able to write**, **without opening ports** and **without losing the vendor's support**. Writing
+never goes through the bridge: it goes through the [official import file](file-exchange.md).
+
+The real "read-only" guarantee lives **in the database**: a login with minimal permissions over
+curated views. The "read-only mode" of an MCP server is almost always a statement filter. It helps;
+it is not enough.
+
+The scripts are in [`../bridge-kit/`](../bridge-kit/README.md), shipped unmodified from their source
+(Spanish comments and file names; see `../THIRD_PARTY.md`). This page is how to use them.
+
+## Architecture
+
+```
+[Program's server or PC]                                       [Agent]
+  SQL Server (production)
+     └─ nightly backup → restore into ERP_IA (copy)       ┌─ Claude Code on a laptop ── Tailscale (grant to the MCP port only)
+           └─ schema "ia": curated views                  │
+                └─ login ia_lectura (SELECT on "ia")      │
+                     └─ DBHub (readonly, predefined SQL) ─┤
+                        listening on 127.0.0.1            └─ claude.ai connector / cloud n8n ── Cloudflare Tunnel + Access
+```
+
+## Step by step
+
+### 0. Permission first
+
+Ask the distributor (Sage, ICG, Prevengos, CONTPAQi, Wolters Kluwer…) whether creating a login and
+views affects support, **in writing** ([messages](messages.md), B). If it does, work **only on the
+copy** (step 1). Some vendors put database reading outside support altogether (Prevengos, for one).
+
+### 1. Isolate the data: a nightly copy
+
+- **SQL Server, Express included.** Express has **no SQL Server Agent**. The pattern is the Windows
+  Task Scheduler plus `sqlcmd`: a `BACKUP ... WITH COPY_ONLY` of production (it does not break the
+  program's own backup chain) and a `RESTORE` into a separate database, `ERP_IA`, every night off
+  hours. `bridge-kit/sqlserver/copia-nocturna.ps1` does it: backup, restore with the file moves,
+  recreate the user and views (the restore wipes them), run the acceptance test, keep three days
+  of backups, log every step.
+- **Access** (`.mdb`/`.accdb`, e.g. FactuSOL local): copy the file off hours and convert the copy to
+  SQLite: `bridge-kit/access/access_a_sqlite.py --origen <file> --destino <file.sqlite>`. It copies
+  first, skips binary attachments and replaces the target atomically. **Never** connect an MCP to
+  the live `.mdb`.
+- **Production** only when real time is truly needed, and then with the login of step 2 and row and
+  time limits.
+
+Schedule the copy with an account that administers SQL Server, **never** with the reader:
+
+```powershell
+$accion = New-ScheduledTaskAction -Execute "powershell.exe" -Argument '-ExecutionPolicy Bypass -File C:\KitPuente\sqlserver\copia-nocturna.ps1 -Origen "<PROGRAM_DB>"'
+$cuando = New-ScheduledTaskTrigger -Daily -At 2am
+Register-ScheduledTask -TaskName "KitPuente copia nocturna" -Action $accion -Trigger $cuando -RunLevel Highest
+```
+
+### 2. A read-only login over views
+
+`bridge-kit/sqlserver/01-login-servidor.sql` (once, server level) and `02-usuario-y-vistas.sql`
+(database level, idempotent):
+
+1. A schema `ia` with **curated views**: only the columns needed. No IBANs, no health data, no
+   payroll. One view per business question.
+2. A login `ia_lectura` that is **not** `sa`, `db_owner` or `sysadmin`, with a long random password
+   kept only on the server.
+3. `GRANT SELECT ON SCHEMA::ia`. The views belong to `dbo`, so ownership chaining lets the login read
+   the tables **through** them without any permission on the tables. Plus `db_denydatawriter` and
+   `DENY CREATE TABLE/VIEW/PROCEDURE/FUNCTION`.
+4. The view templates use placeholders (`<tabla_facturas_emitidas>`, `<columna_fecha>`…). Table and
+   column names depend on the program and its version and are **not public**: confirm them with the
+   distributor.
+
+If the server only allows Windows authentication, use a dedicated Windows account instead of the
+SQL login.
+
+### 3. The acceptance test
+
+`bridge-kit/sqlserver/03-prueba-solo-lectura.sql` impersonates `ia_lectura` inside a transaction it
+rolls back, and checks: it **can** read the `ia` views; it **cannot** read the tables directly,
+delete, update or create a table. It must end in `RESULTADO: OK`. Without it, the agent is not
+connected.
+
+> **Check this before trusting an OK.** The script counts *any* error on the forbidden statements
+> as a pass. If a placeholder such as `<tabla_facturas_emitidas>` was not replaced, or the table
+> name is wrong, those statements fail with "invalid object name", not with a permission error,
+> and the test reports OK without proving anything. Replace every placeholder with a real table,
+> and confirm that the errors are permission errors (`Msg 229` / `Msg 262`), the same rule as the
+> `test_connection` probes in SKILL.md.
+
+### 4. The database MCP server
+
+| Option | When | Read-only | Limiting tables | Notes |
+|---|---|---|---|---|
+| **DBHub** (Bytebase, MIT) — the kit's choice | SQL Server, PostgreSQL, MySQL/MariaDB, Oracle, SQLite | `readonly=true` per tool in `dbhub.toml`: only SELECT, SHOW, DESCRIBE, EXPLAIN, PRAGMA. A filter: combine it with the login | **Predefined SQL tools** with typed parameters | npx or Docker; several sources in one TOML; `max_rows`; SSH tunnel. Over HTTP, a shared bearer token. No Windows integrated auth |
+| **SQL MCP Server** (Microsoft, Data API builder 2.x, MIT) | SQL Server, Azure SQL, PostgreSQL, MySQL | Per-role permissions (e.g. `anonymous:read`), no free SQL | Only the entities declared in `dab-config.json` | Over HTTP everything enters as **anonymous** by default: put JWT/Entra ID or Cloudflare Access in front. Needs .NET |
+| **mcpFirebird** (MIT) | Firebird | `allowedOperations=['SELECT']`, no free SQL | `allowedTables` | Low-to-medium maturity |
+| Access | — | — | — | No mature MCP: **copy → SQLite → DBHub** |
+
+SQL Server MCP servers with no read-only mode do not belong in the bridge.
+
+`bridge-kit/dbhub/dbhub.toml.ejemplo` has one tool per business question ("sales per day",
+"pending collections", "stock below minimum"), each a `SELECT` on the `ia` views, so the agent does
+not improvise SQL against the program. `execute_sql` cannot be removed according to DBHub's docs:
+it stays `readonly` with a row cap. The file holds the reader's password: keep it on the program's
+server, readable only by the account that runs DBHub, never in git or on a laptop. **DBHub listens
+on `0.0.0.0` by default: always pass `--host`**, and pin the npm version.
+
+### 5. The network: no open ports
+
+**Rule:** port 1433 (and any database or MCP port) is **never** opened on the router. MS-SQL servers
+exposed to the internet are a classic ransomware entry for small businesses.
+
+| If the agent is… | Use | How it is limited | Indicative cost |
+|---|---|---|---|
+| Claude Code on the owner's laptop | **Tailscale** | Tag `tag:erp` on the server and a grant that lets only the owner reach **the MCP port** (not 1433). `bridge-kit/red/tailscale-grants.hujson` | Standard plan per user per month; the Personal plan is non-commercial only. Check current pricing |
+| A claude.ai remote connector, Cowork or cloud n8n | **Cloudflare Tunnel + Access** in front of the MCP's HTTP endpoint | Access application with an email policy, service tokens for machines; the MCP listens on 127.0.0.1 with its own token. `bridge-kit/red/cloudflared-config.yml.ejemplo` | Zero Trust has a free tier (check the current limit). Needs a domain on Cloudflare |
+
+Remote claude.ai connectors leave from Anthropic's infrastructure and **do not reach a VPN or
+Tailscale**. Using the bridge from claude.ai or Cowork needs the Cloudflare tunnel.
+
+### 6. In the harness
+
+`01-TOOLS/<PROGRAM>/`, from `bridge-kit/01-TOOLS-plantilla/`:
+
+- `.env`: the MCP URL and token (`ERP_MCP_URL`, `ERP_MCP_TOKEN`), **not** the database password,
+  which stays on the program's server. The kit's README mentions an `.env.example` that the source
+  does not ship: write it with those two variables.
+- `test_connection.sh`: initialises the MCP, lists its tools and warns about any tool the kit did
+  not expect. It proves the bridge answers; the read-only proof is test 03 on the server.
+- `CREDENTIALS.md`: who created the login, where the copy lives, when the token rotates (every
+  quarter).
+
+Plus the entry in `.mcp.json`.
+
+## Plan B: an export folder
+
+When no database is reachable: a nightly CSV export to a folder (Task Scheduler with `sqlcmd`/`bcp`
+over the views, or the program's own export) and the harness reads the folder. Details in
+[file exchange](file-exchange.md). With n8n: version 2 disables the Local File Trigger and Execute
+Command by default; re-enable them deliberately and restrict paths with
+`N8N_RESTRICT_FILE_ACCESS_TO`, and keep n8n updated.
+
+## When to pay instead of building: unified APIs
+
+| Service | Spanish coverage (check current list) | Local or cloud | MCP | Watch for |
+|---|---|---|---|---|
+| **Chift** | Holded, ContaSOL (cloud only), a3ERP, Sage 200 ES, Odoo, Ágora, Revo, Business Central… | Both: Sage 200 ES and a3ERP through a local Windows agent (outbound, no ports) | Yes, official | Asks for broad permissions (read and write). Price not public |
+| Apideck | Holded, Odoo | Cloud | Yes | Expensive for a small business |
+| Unified.to | Holded, Odoo, Sage 200 (beta) | Cloud | Yes | — |
+
+For a single small business the own bridge is usually cheaper. Check coverage and prices at the
+source before recommending one.
+
+## What the bridge does not do
+
+- It does not write into the program: that is the import file.
+- It ships no table schemas of commercial programs.
+- It does not replace the vendor's support: when the program updates and changes its tables, the
+  views need review. Test 03 and `test_connection` detect it.

package/skills/connect-tool/references/file-exchange.md

@@ -0,0 +1,103 @@
+# File exchange: reading exports, generating imports
+
+A route of its own, with its method and its proof. Most small-business programs export to Excel or
+CSV and import an official file, even when they have no API. **To read**, the program exports to a
+folder and the agent reads. **To write**, the agent generates the program's official import file and
+a person imports it.
+
+Reading this way is often the best first route for an installed program: it needs no database
+access, keeps the vendor's support, and takes an afternoon. Writing this way is the **only** safe
+way to write into an installed accounting or invoicing program.
+
+## Reading: an export to a folder
+
+1. **Choose what comes out.** Few, useful things: sales of the day, pending invoices, stock, open
+   jobs. Only the columns needed (GDPR).
+2. **Find the function in the program.** Almost every program exports its list screens to Excel or
+   CSV. Some export by FTP, set up by the distributor. Construction software exports BC3, a plain
+   text standard any script can read.
+3. **Schedule it.** The program's own scheduler if it has one; otherwise the Windows Task Scheduler
+   or a script run by the IT person. If it cannot be automated, a weekly manual export is a valid
+   start.
+4. **Choose the folder.** A folder on a server or synced with OneDrive or Google Drive. The program
+   only writes there; the agent only reads.
+
+Rules for the folder:
+
+- The exporter writes to a temporary name and **renames at the end**: a half-written file must
+  never be read.
+- File events are not reliable on network shares (SMB/NFS) or Docker volumes on Windows: read on a
+  schedule instead of on change.
+- **Validate the structure of every file** against the described format, and warn when it changes:
+  a program update breaks a parser silently.
+- The data is as fresh as the last export. Say so to the user.
+
+## Writing: the official import file
+
+The agent does not write in the program. It reads the source (invoices, tickets, an Excel), proposes
+the records, and generates the program's **official import file** in `01-TOOLS/<TOOL>/out/`
+(gitignored). A person reviews it, runs the program's own validation, and imports it with the
+program's button. So the program's integrity and support stay intact, the Spanish Veri\*factu record
+chain is never touched, and a person always says "yes" before anything enters the books.
+
+Rules:
+
+1. **Sample file first.** Before generating anything, get a file exported from the user's own
+   program, or the vendor's official examples, and copy its structure exactly. Fixed-width
+   positions change between versions.
+2. **Existing accounts only.** The file uses accounts from the current chart of accounts. A missing
+   one is flagged for review, never invented. (Some programs **create** an unknown account on
+   import: a typo becomes a new sub-account.)
+3. **Totals balance.** Base + tax = total on every invoice; debit = credit on every entry. If it does
+   not balance, it does not leave.
+4. **No duplicates.** A batch log (supplier + number + amount + batch) in
+   `01-TOOLS/<TOOL>/out/lotes.csv`, checked before every new file.
+5. **The person imports.** After the program's validation and a backup.
+6. **Never issue.** The agent does not create **issued** invoices in an invoicing program. It
+   prepares data or drafts; a person issues from the program.
+
+## Describe the format
+
+In `01-TOOLS/<TOOL>/README.md`, for every file read or generated:
+
+| Property | Example |
+|---|---|
+| Columns, in order, with type | `fecha` date · `cuenta` text(10) · `debe` decimal · `haber` decimal |
+| Encoding | Windows-1252 (common in Spanish desktop programs) or UTF-8, with or without BOM |
+| Separator | `;` (Spanish Excel default), `,`, tab, or fixed width |
+| Decimal mark | `,` or `.`; thousands separator, if any |
+| Date format | `dd/mm/yyyy`, `yyyymmdd`… |
+| Fixed widths | positions and lengths, for fixed-width formats |
+| Line ending | CRLF or LF |
+
+## The proof
+
+`test_connection` for this route checks:
+
+- **Reading:** the latest export exists, is **recent** (within the expected schedule) and **matches
+  the described format** (columns, encoding, separator). A stale or changed file fails the test.
+- **Writing:** a generated file validates: structure, balances, existing accounts, no duplicates.
+- **The first import** is done in the program's **test company** (most accounting programs have
+  one, or the user creates one), never in the real books. Only after that test import looks right
+  does the route go live.
+
+## Formats of common Spanish accounting programs
+
+Checked against vendor documentation on 2026-10-09 (source: see `../THIRD_PARTY.md`). Formats and
+positions change between versions: always generate a sample from the user's own program and
+compare.
+
+| Program | Format | What it imports | Paid? | Main risks |
+|---|---|---|---|---|
+| **A3 (a3asesor eco/con)** | **SUENLACE.DAT**: fixed-width ASCII, 512-byte records. Type at position 15: 0 entry without VAT, 1 invoice with VAT, 2 corrective, 9 VAT detail, C new accounts, V/B due dates, A/D analytics | Entries, issued and received invoices with VAT and SII, corrective invoices, accounts, due dates, analytics | No (standard). Excel-to-link importers are separate | An unknown account is **created automatically**. Always run the **Chequeo**. Official examples in the install: `SUENLAC5.TXT`, `SUENLAC5.EJE` |
+| **a3innuva Contabilidad** | **Importia** (Excel with a column wizard and .zip templates) or the **API** with entries and invoices in **Draft** | Issued and received invoices, entries, chart of accounts, payroll link | Yes: Importia and Conectia (API) are separate subscriptions | Re-importing without "undo" duplicates. A wrong VAT operation code misclassifies |
+| **Sage 50 (Spain)** | Free **entry import/export** add-on: three files (sub-accounts, journal, notes) as fixed-width .txt, .csv or .dbf, ContaPlus-compatible | Entries (VAT in the journal), sub-accounts, notes. **Not** invoices as sales documents | No (enable it in Add-ons) | Import in order: accounts → entries → notes. Shorter account codes are zero-padded and can land on the wrong sub-account. No blank template: export a sample entry and copy it |
+| **Sage 200 (Spain)** | **Import manager** with Excel guides (entries, invoices plugin) | Customers and items (official); entries and invoices as entries through guides or plugins | Probably (partner guides) | Empty invoice type after import → incomplete VAT books. With its Veri\*factu module, invoices certified by other software are not imported |
+| **ContaSOL** (and FactuSOL → ContaSOL) | Excel books with fixed names: **APU** (journal), **FRE + LFR** (received), **FAC + LFA** (issued), **PLA + LPL** (templates). Also ContaPlus ASCII and the ASCII Connector | Entries, invoices (VAT books), master data, opening | No (Utilities > Imports) | Different account lengths fail. Fields too long are **dropped silently**; text in a numeric field becomes 0. The Connector writes straight into the DATOS folder: back up first |
+| **ContaPlus** (legacy) | XDiario, XSubCta, XDatAsi (fixed-width .txt or .dbf) | Entries, sub-accounts, comments | No | No official support for years. Still an exchange format Sage 50 and ContaSOL accept, but VAT may not reach the books and form 303 correctly |
+| **Holded** | Excel/CSV templates: Journal, Accounts, Sales, Purchases, Contacts | Entries, chart of accounts, sales and purchase invoices, contacts | No | Widen account digits **before** creating data. Contacts must exist (matched by tax ID). Undo is not documented |
+| **Odoo** | Generic importer (CSV/XLSX) on `account.move` and its lines | Entries, invoices, contacts, statements | No | **Imports are permanent**: use "Test" and small batches, with External IDs to avoid duplicates. Entries stay in **draft** (good for review). With Veri\*factu active, posting a customer invoice sends it to the tax agency |
+
+Other programs: ask the distributor which import format they accept, and get a sample.
+
+What changes with Spanish B2B e-invoicing, and why import files are unaffected: [Spain](spain.md).

package/skills/connect-tool/references/messages.md

@@ -0,0 +1,120 @@
+# Messages: asking whoever holds the key
+
+Used in option 2, when the connection depends on someone else. Write the message in the user's
+language and register, change what is between `<…>`, remove what does not apply, and add no
+requests that are not needed. Every message keeps four things: **read-only**, **a dedicated user**,
+**nothing open to the internet**, and **the cost question**. If `unslop` is installed, pass the
+message through it.
+
+The person on the other side does not need to know what an "AI harness" is. Ask for concrete,
+familiar things: a read-only credential, in the name of an integration, with the least access.
+
+## Before writing: five facts
+
+1. The exact name and version of the program ("Sage 200 2025", "ContaSOL 2026").
+2. Where it is installed: the vendor's cloud, an office server, someone's PC, the distributor.
+3. Who maintains it: own IT person, distributor, vendor, accounting firm.
+4. Exactly which data: "issued and received invoices for the last 12 months", not "everything".
+5. Read only, or also write. Start with read.
+
+## A. Installed program → IT person or distributor
+
+> Hi `<name>`. I want to automate `<sales and collections reports / entering invoices>` with an AI
+> tool. It needs to read data from `<program and version>`. In order of preference:
+>
+> 1. Do you or the vendor have an **API or integration module** for this program, or a cloud
+>    edition with an API? What does it cost?
+> 2. If not, can the program **export automatically** every night `<invoices, customers, stock>`
+>    to CSV or Excel in a folder?
+> 3. If not, can you create a **read-only database user** limited to `<these views>`, reachable
+>    only through a VPN?
+>
+> I do not need to write anything in the program. I do not want to open ports to the internet or
+> use the administrator account. Which option do you see, and what would it cost?
+
+## B. The vendor itself (no reply from the distributor, or no distributor)
+
+> Subject: Integration enquiry for `<program>` version `<version>`
+>
+> Hello. We are licensed customers (`<licence number or tax ID>`). We want to connect `<program>`
+> to an analysis tool of our own, **only to read data** (`<sales / invoices / customers / jobs>`).
+>
+> 1. Is there a module, API, web service or automatic export? For which version and licence?
+> 2. If not, can we have a **read-only database user** on views without losing support? Please
+>    confirm in writing.
+> 3. Is there technical documentation? What does it cost (setup, fee, hours)?
+> 4. Do you have a cloud edition with an API?
+>
+> Thank you. `<name, phone>`
+
+Asking also leaves in writing whether support is kept.
+
+## C. Program hosted by the distributor (remote desktop, Citrix)
+
+> Hi `<name>`. We use `<program>` on your hosted service. We want an AI tool to read
+> `<invoices, customers, stock>` for internal reports. Since the program runs on your side:
+>
+> 1. Can you schedule an **automatic export** of that data to a folder we can reach (SFTP or a
+>    shared drive)? How often?
+> 2. Do you offer an **API or integration module** for the hosted version?
+> 3. Could you give us a **read-only user** on a copy of our data, on your side?
+>
+> We do not need to write anything. What does each option cost?
+
+## D. Accounting firm (the program is theirs)
+
+> Hi `<name>`. We are automating our internal reports. Could you leave in a shared folder, every
+> `<week / month>`, `<the balance sheet, the customer and supplier ledgers, filed tax returns>` in
+> Excel? If your program can give the company read-only access to its own data, that works too.
+
+When the program belongs to the accounting firm, the owner asks the firm, not their own IT person.
+
+## E. Web tool run by someone else (accounting firm, agency, partner)
+
+> Hi `<name>`. Could you create in `<tool>` a **read-only API key or integration user** named
+> "rsc-read"? It is for automatic reports. If the tool cannot limit permissions, tell me before and
+> we discuss it.
+
+## F. Google Workspace → administrator
+
+> Hi `<name>`. I need to authorise an app with **read-only permissions**
+> `<gmail.readonly / drive.file / spreadsheets.readonly / calendar.events.readonly>`. In API
+> controls, keep it under "Specific Google data" and, if possible, limit it to `<this folder or
+> sheet>` by sharing it with a service account without domain-wide delegation. Consent screen
+> "Internal".
+
+## G. Microsoft 365 → administrator
+
+> Hi `<name>`. I need to register an app in **Entra ID** with read-only delegated permissions
+> (`User.Read`, `Mail.Read`, `Files.Read`…) or, if it runs without a user, `Sites.Selected` with
+> the "read" role on the site `<name>` only. It needs admin consent and "Assignment required" for
+> my user only. No write permissions on the whole tenant.
+
+If the company only authorises Copilot, do not force another AI: suggest Copilot Studio or Power
+Automate, or ask for the exception in writing.
+
+## H. WhatsApp Business → provider (BSP or Tech Provider)
+
+> Hello. We want to register our number on the WhatsApp Business Platform in **coexistence**, so we
+> keep using the app on the phone. Do you do that? What does it cost per month and per
+> conversation? Do we get API and webhook access, or only your dashboard? We need a system user
+> with access to our WABA only.
+
+The WhatsApp Business *app* has no API. Unofficial tools that read WhatsApp Web get the number
+blocked.
+
+## When they say "that cannot be done"
+
+Ask:
+
+1. "Can it **export** to Excel or CSV, even by hand?" If yes, there is a starting point.
+2. "Does the vendor have **partners or integrators** who connect it?"
+3. "Is there a **cloud edition** of the program?" They usually come with an API.
+4. "What would it take for it to be **read-only and with nothing open to the internet**?"
+
+## What is not accepted
+
+- The administrator's password, or another person's user.
+- Opening the database or remote desktop port to the internet "so it works".
+- A key that can do everything when a limited option exists.
+- Credentials sent by email or WhatsApp. They are pasted directly into `01-TOOLS/<TOOL>/.env`.

package/skills/connect-tool/references/program-types.md

@@ -0,0 +1,97 @@
+# Program types: recognise the program, know what it allows, know who to ask
+
+Option 2 starts here: the user has a program with no API, no MCP and no usable docs, and does not
+know what kind of program it is. Their answers to the diagnosis questions place it in one of these
+types. **They are a guide, not a closed list.** A program can sit between two types (a desktop
+program with a cloud backup, a hosted program that also exports files). Say which type it looks
+like, how sure you are, and what would confirm it.
+
+## The diagnosis questions, and what each answer tells you
+
+| Question (plain words) | If yes | If no |
+|---|---|---|
+| Do you log in with a username and password on a website? | Vendor web app. Docs exist more often than the user thinks: back to research | Installed somewhere |
+| Does it keep working when the internet goes down? | The data is local: on this PC or an office server | Web app, or hosted by the distributor |
+| Do several computers see the same data? | Client-server: a database on an office server or one shared PC | Single-PC desktop program |
+| Do you open it through remote desktop, Citrix, or an icon that connects elsewhere? | **Hosted by the distributor**: the data is not in the office | Installed in the office |
+| What extension do the files in its data folder have? | `.mdf` SQL Server · `.mdb`/`.accdb` Access · `.fdb`/`.gdb` Firebird · `.dbf` dBase · `.btr`/`.dat` Btrieve · `.db` Paradox or SQLite | (unknown: ask whoever installed it) |
+| Who do you call when it breaks? | That person or company **holds the key** | Nobody: the owner decides alone, and support may be over |
+
+Help the user answer: the data folder is usually under the program's install folder or a path in
+its settings; *Help > About* gives the exact version; the vendor's invoice names the distributor.
+
+## The types
+
+### Vendor web app (SaaS)
+
+- **Recognise it:** a website with a login, works from any computer, monthly subscription.
+- **What it allows:** almost always an API, an official integration or an export. If research
+  found nothing, search again with the vendor's other product names, and look for an
+  "Integrations", "API" or "Developers" page inside the app's settings.
+- **Who holds the key:** the account administrator. Sometimes that is the accounting firm or an
+  agency, not the owner.
+- **Ask:** an API key or integration user, read-only, in the name of an integration, not a person.
+
+### Desktop program with a local database
+
+- **Recognise it:** works offline, one PC, data folder on that PC. Common engines: SQL Server
+  Express (`.\SQLEXPRESS`), Access, Firebird.
+- **What it allows:** file exchange (exports and official imports), or a read-only copy of the
+  database ([database bridge](database-bridge.md)).
+- **Who holds the key:** the owner for the PC; the distributor for whether reading the database
+  keeps support.
+- **Ask:** the database engine, whether exports can be scheduled, and the support terms in writing.
+
+### Client-server in the office
+
+- **Recognise it:** several PCs see the same data; one machine (a server or "the main PC") must be
+  on. The database is on that machine.
+- **What it allows:** the same as a desktop program, with the copy and the reader on the server.
+- **Who holds the key:** the IT person who looks after the server, and the distributor for support.
+- **Ask:** a read-only user on a nightly copy, reached only privately; never a port open to the
+  internet.
+
+### Hosted by the distributor (remote desktop, Citrix)
+
+- **Recognise it:** the user opens a remote desktop or a Citrix icon; nothing of the program is in
+  the office; it may keep working from home.
+- **What it allows:** **no database to copy and no folder the agent reaches.** The only door is the
+  provider: an export they schedule to a folder the client can reach (SFTP, a shared drive), an
+  integration module, or a read-only user on their side.
+- **Who holds the key:** the distributor or hosting provider, always.
+- **Ask:** whether they can drop a scheduled export somewhere the client can read; whether they
+  offer an API or integration module; what it costs. Never try to reach their servers any other way.
+
+### Old file database (dBase, Btrieve, Paradox)
+
+- **Recognise it:** an old program, many small data files (`.dbf`, `.btr`, `.dat`), often a
+  Windows program from the 1990s or 2000s, sometimes still running under compatibility mode.
+- **What it allows:** reading **a copy** of the files with a library for that format (dBase reads
+  easily; Btrieve needs its engine or the vendor's description of the records). The program's own
+  export is safer when it exists.
+- **Who holds the key:** often nobody: the vendor may no longer exist. The person who uses it daily
+  knows its exports.
+- **Ask:** what exports the program has; whether the vendor still supports it. This type is a
+  strong candidate for [connect or migrate](connect-or-migrate.md).
+
+### Linux server or AS/400 (IBM i)
+
+- **Recognise it:** green-screen terminal, or a program the IT person describes as "the server".
+  Common in larger or older companies, distribution and manufacturing.
+- **What it allows:** a database that is usually queryable (Db2 for i on AS/400; PostgreSQL,
+  MySQL or a proprietary engine on Linux) and scheduled exports, both set up by the IT person.
+- **Who holds the key:** the IT person or the company that maintains the system.
+- **Ask:** a read-only user on the views needed, or a scheduled export; how they reach it
+  privately.
+
+### Not a program: Excel or a shared folder
+
+- **Recognise it:** "our ERP is an Excel".
+- **What it allows:** move the file to OneDrive or Google Drive and connect that; or read a copy
+  from a synced folder. No bridge needed.
+
+## After placing it
+
+Tell the user, in short sentences: the type it looks like, what can be tried, what they must
+confirm, and who to ask. Then the closed questions for that person (SKILL.md, option 2, step 3),
+and the case left open in `02-DOCS`.

package/skills/connect-tool/references/spain.md

@@ -0,0 +1,103 @@
+# Spain: invoicing rules and the files Spanish programs exchange
+
+Load this only when the business is in Spain. Dates and rules below were checked on 2026-10-09
+(sources at the end). **They move: check the tax agency (AEAT) and the BOE before quoting any date
+to the user**, and say which date you checked.
+
+## The line that matters: prepare vs issue
+
+- **Preparing** an invoice (gathering what to bill, computing amounts, a draft, a payment reminder)
+  can be done by the agent, a spreadsheet or a script.
+- **Issuing** it (numbering, signing, chaining, recording, and in Veri\*factu mode sending to the
+  AEAT) is done by **invoicing software that complies with the regulation**, with a person who
+  presses the button.
+
+| Piece | Who can do it |
+|---|---|
+| Gather and compute what to invoice | Agent, Excel, script |
+| Create the invoice as a **draft** in the program | Agent through the API, with a dedicated user and approval |
+| **Issue** it (number, chain, sign, send to the AEAT) | **The invoicing program**, with a person pressing |
+| Warn about collections and overdue invoices | Agent (read-only, plus drafts of the messages) |
+| Build its own issuing system | Only when assuming full compliance; not recommended for a small business |
+
+An agent never "connects to Veri\*factu" by itself. It drafts; the compliant program issues and
+sends the record.
+
+## Veri\*factu (invoicing systems regulation)
+
+- **What it requires** (RD 1007/2023): the software that issues invoices guarantees integrity,
+  conservation, accessibility, legibility, traceability and inalterability of the records. Each
+  invoice carries a fingerprint chained to the previous one: a numbered, stamped invoice book where
+  no page can be torn out or rewritten without a trace. In **Veri\*factu** mode the program also
+  sends every record to the AEAT almost as it issues it; the other mode keeps its own signature and
+  event log.
+- **Responsible declaration**: the software producer signs one per version, visible inside the
+  program (Orden HAC/1177/2024). **The AEAT does not certify programs**: there is no "approved by
+  Hacienda" seal. Ask for the declaration and the exact version, in writing.
+- **Dates, as checked on 2026-10-09**: before **1 January 2027** for corporate income tax payers and
+  **1 July 2027** for everyone else, self-employed included (RDL 15/2025). On 5 October 2026 the
+  Treasury **announced** a postponement to October 2028; no published rule formalised it at the date
+  checked. Plan with the legal dates and treat the postponement as possible, not certain.
+- **Out of scope**: businesses in the SII, and the foral territories with TicketBAI or Batuz.
+- **Software vendors** may only sell adapted systems with a declaration since 29 July 2025.
+- **Own software**: the regulation applies to any taxpayer using an invoicing system, own or third
+  party. An app built with Claude Code that stores, numbers and issues invoices **is** an invoicing
+  system and must meet all of the above. The AEAT has FAQs on own software: read them before
+  deciding.
+- **Never** let an agent edit invoices in an invoicing program's database: it breaks the chain.
+
+## B2B e-invoicing
+
+- **RD 238/2026** and **Orden HAC/1028/2026** (BOE of 5 October 2026): e-invoicing between
+  businesses becomes mandatory on **6 October 2027** for those invoicing more than €8M and on
+  **6 October 2028** for everyone else.
+- Structured format following EN 16931 (UBL, CII, EDIFACT or Facturae); the AEAT's public solution
+  uses UBL. A PDF no longer counts between businesses. A private platform must send a UBL copy to
+  the public solution.
+- Each invoice is identified by issuer tax ID + series + number + date.
+- The receiver reports acceptance, rejection and payment; the issuer can report collection or
+  non-payment. Reporting statuses becomes a new, mandatory write: a good candidate to automate,
+  with human approval.
+- It is the real migration trigger for old programs: the program must issue and receive UBL or
+  Facturae. Ask the vendor in writing ([connect or migrate](connect-or-migrate.md)).
+
+Effects on connections:
+
+1. **Accounting import files are not invoices** and do not change. They remain the right way for a
+   person to validate an entry ([file exchange](file-exchange.md)).
+2. **Received invoices will arrive as structured XML.** The agent reads tax IDs, bases and taxes
+   without OCR and keeps the XML as the supporting document.
+3. **Issued invoices**: the agent does not generate or sign UBL or Facturae on its own, nor call
+   issuing endpoints. It leaves data or drafts for the adapted program.
+4. **An invoice already issued elsewhere only enters accounting.** It is never re-issued by
+   importing it into another program's invoicing module.
+
+## File formats Spanish programs exchange
+
+| Format | What it is | Where it appears |
+|---|---|---|
+| **SUENLACE.DAT** | A3's accounting link file: fixed-width ASCII, 512-byte records | a3asesor imports; accounting firms that use A3. Details in [file exchange](file-exchange.md) |
+| **ContaPlus files** (XDiario, XSubCta) | Legacy fixed-width or dBase exchange format | Still accepted by Sage 50 and ContaSOL |
+| **ContaSOL books** (APU, FAC/LFA, FRE/LFR) | Excel books with fixed names | ContaSOL imports; FactuSOL passes invoices to ContaSOL |
+| **Norma 43** | The Spanish banking standard (AEB/CSB 43) for account statements: fixed-width text | Exported by every Spanish bank's online banking; imported by accounting programs for bank reconciliation. A clean read-only source of movements |
+| **Facturae** | Spain's structured XML e-invoice, mandatory with the public administration (FACe) | Invoicing programs; accepted for B2B e-invoicing |
+| **UBL** (EN 16931) | The European structured e-invoice | The AEAT public solution for B2B e-invoicing |
+| **BC3** (FIEBDC-3) | The construction standard for budgets, price databases and measurements: plain text | Presto and construction software; installer software imports it |
+| **SII** | Immediate VAT information supply to the AEAT | Larger companies; A3 and others carry SII fields in their import files |
+
+Norma 43, Facturae and BC3 are public standards: a script reads them without the program that wrote
+them. Still copy the structure from a real sample.
+
+## Sources
+
+Checked on 2026-10-09; adapted from Executive Lab's guides (see `../THIRD_PARTY.md`).
+
+1. AEAT, Sistemas informáticos de facturación y Veri\*factu: https://sede.agenciatributaria.gob.es/Sede/iva/sistemas-informaticos-facturacion-verifactu.html
+2. AEAT, note on the extended adaptation period: https://sede.agenciatributaria.gob.es/Sede/iva/sistemas-informaticos-facturacion-verifactu/nota-informativa-ampliacion-plazo-adaptacion-facturacion.html
+3. BOE, Orden HAC/1028/2026: https://www.boe.es/diario_boe/txt.php?id=BOE-A-2026-20587
+4. BOE, Real Decreto 1007/2023: https://www.boe.es/buscar/act.php?id=BOE-A-2023-24840
+5. BOE, Orden HAC/1177/2024: https://www.boe.es/buscar/act.php?id=BOE-A-2024-22138
+6. BOE-A-2026-7295, cited by the source guide for B2B e-invoicing: https://www.boe.es/diario_boe/txt.php?id=BOE-A-2026-7295
+
+Not verified at that date: the AEAT FAQ text on own software, the full text of RD 238/2026, a rule
+formalising the postponement, penalties.

package/skills/connect-tool/references/what-to-find-out.md

@@ -0,0 +1,57 @@
+# What to find out, where to look, how to write it down
+
+Research replaces any catalogue. A list of vendors is out of date within months: prices, plans,
+endpoints and MCP servers change, and it only covers what someone already entered. The fields below
+are what such a catalogue held. Fill them for **this** tool, now, from primary sources, and write
+them into `01-TOOLS/<TOOL>/README.md`. That file is the catalogue entry for this project.
+
+## The fields
+
+| Field | The question | Where to look first |
+|---|---|---|
+| **API** | Is there a documented API? REST, GraphQL, SOAP web service? Which plan includes it? | Vendor developer portal; "API", "Developers", "Integrations" in the app's settings |
+| **MCP** | Is there an official MCP server? A maintained community one? Read-only mode? | `registry.modelcontextprotocol.io`; the vendor's docs; the vendor's GitHub |
+| **Other routes** | Cloud edition with an API, vendor or distributor integration module, unified API (e.g. Chift), built-in Zapier/Make/n8n connector | Vendor site, distributor site, the unified API's coverage list |
+| **Exports** | What can it export, in which format, and can it be scheduled or dropped to a folder or FTP? | The user manual; the program's list screens ("Export to Excel") |
+| **Imports** | What official import formats does it accept, for which objects (entries, invoices, customers, items)? | The user manual; vendor support articles |
+| **Database** | Which engine does an installed program use? Is reading it allowed by the support terms? | Install guide; the data folder's file extensions; the distributor |
+| **Scoped permissions** | Can the credential be limited (read scopes, modules, sites, folders)? What **cannot** be limited? | Token or app settings; vendor docs on scopes or roles |
+| **Who to ask, and what** | Who activates it (account admin, distributor, IT person, accounting firm) and the exact request | The vendor's "how to activate" page; the user's answers |
+| **Free trial** | Free tier, trial, sandbox, developer account, test company. Does the trial include the API? | Pricing page; developer portal |
+| **Cost** | Minimum cost with API access; module or connector fees | Pricing page; ask the distributor in writing |
+| **Migration** | Is the product near end-of-life? Does a successor exist? | Vendor roadmap, end-of-support notices |
+| **Spain** | Veri\*factu declaration for the exact version; B2B e-invoicing readiness | The vendor's responsible declaration; see [Spain](spain.md) |
+| **Sources and confidence** | URL and date for every claim; "verified", "secondary source" or "not verified" | — |
+
+Leave a field as **unknown** rather than guessing. "Not found after searching X, Y and Z on
+<date>" is a result; an invented endpoint is a week lost.
+
+## Where to look, in order
+
+1. The vendor's own domain: developer docs, help centre, pricing, legal pages.
+2. Official registries: the MCP registry; app marketplaces of the platform (Google Workspace
+   Marketplace, Microsoft AppSource, Shopify App Store…).
+3. The distributor or partner's site, for modules the vendor does not list.
+4. Secondary sources (forums, blog posts, partner presentations) only to find leads. Mark anything
+   that comes only from them as **not verified**.
+
+## How to write it down
+
+In `01-TOOLS/<TOOL>/README.md`:
+
+```markdown
+## Research — checked 2026-11-01
+
+| Field | Finding | Source (date) | Confidence |
+|---|---|---|---|
+| API | REST, invoices and contacts read; needs the Pro plan | https://… (2026-11-01) | verified |
+| MCP | None official; community server unmaintained since 2025 | https://… (2026-11-01) | verified |
+| Exports | Scheduled CSV of invoices to a folder | user manual, ch. 12 (2026-11-01) | verified |
+| Free trial | 30 days, API included | https://… (2026-11-01) | not verified: page says "most features" |
+```
+
+## The 60-day rule
+
+Before relying on an existing `README.md`, look at its dates. **More than 60 days old: check the
+sources again** before quoting a price, a plan or an endpoint, and update the dates. This is what
+keeps the research current without anyone maintaining a list.