refactor(skills): make skills self-contained with inlined endpoints and official external references only, document knowledge/skills separation in README

Author: francescobianco

README.md

@@ -9,6 +9,16 @@ Agent skills for using and integrating the services of the [Openapi](https://ope
 | [`knowledge/`](knowledge/) | Curated knowledge base: company profile, services catalog, platform guide (auth, billing, sandbox), FAQ, references, per-service endpoint docs and vendored OpenAPI specs |
 | [`skills/`](skills/) | The agent skills, one folder per domain, each with a `SKILL.md` |
 
+## Knowledge / skills separation
+
+The two folders have strictly separated roles:
+
+- **`knowledge/` is build-time material.** It is the mass of curated information used to *create and align* the skills (and to refresh them when Openapi changes). It is consulted by maintainers of this repo, not by agents executing a skill.
+- **`skills/` are self-contained deliverables.** Each `SKILL.md` is *populated from* the knowledge but never *links to* it: an agent must be able to use a skill without this repository's `knowledge/` folder being available.
+- **External references are allowed in skills, but never routed through `knowledge/`.** Skills point directly to official sources — e.g. the canonical specs at `https://console.openapi.com/oas/en/<service>.openapi.json`, the docs portal, the status page — not to local copies of them.
+
+Maintenance flow: update `knowledge/` from the official sources first, then propagate the relevant content into the affected `SKILL.md` files.
+
 ## Skills
 
 | Skill | Covers |

skills/openapi-auth/SKILL.md

@@ -28,20 +28,31 @@ curl -s -u "$OPENAPI_EMAIL:$OPENAPI_API_KEY" https://oauth.openapi.com/tokens \
   }'
 ```
 
-- Scope format: `METHOD:host/path-prefix` (e.g. `POST:sms.openapi.com/messages`). Request only the scopes the task needs, with a short `ttl`.
+- Scope format: `METHOD:host/path-prefix` (e.g. `POST:sms.openapi.com/IT-messages`). Request only the scopes the task needs, with a short `ttl` (max 1 year).
 - Discover valid scopes: `GET https://oauth.openapi.com/scopes` (Basic auth).
-- A refresh token can renew an expired token: `PATCH /tokens/{id}` with the refresh token as Bearer.
+- Optional `limits` object restricts token usage further.
+- A refresh token can renew a token: `PATCH /tokens/{id}` with the refresh token as Bearer.
+- Tokens can also be created from the console UI (Authentication → "+New Token") at https://console.openapi.com.
 
-## Useful management endpoints (Basic auth)
+## Management endpoints (Basic auth)
 
-- `GET /tokens`, `GET|PATCH|DELETE /tokens/{token}` — token lifecycle
-- `GET /wallet`, `GET /wallet/transactions` — credit balance (check before expensive paid calls)
-- `GET /subscriptions` — active plans and remaining requests
-- `GET /stats`, `GET /stats/apis/{domain}` — usage analytics
-- `GET /errors`, `GET /callbacks` — error log and callback monitoring
+| Endpoint | Purpose |
+|---|---|
+| `GET /tokens`, `GET\|PATCH\|DELETE /tokens/{token}` | Token lifecycle |
+| `GET /scopes`, `GET /scopes/{id}` | Available scopes |
+| `GET /wallet`, `GET /wallet/transactions` | Credit balance — check before expensive paid calls |
+| `GET /subscriptions`, `GET /subscriptions/{id}` | Active plans and remaining requests |
+| `GET /stats`, `GET /stats/apis`, `GET /stats/apis/{domain}`, `GET /stats/ips` | Usage analytics |
+| `GET /errors`, `GET /callbacks` | Error log and callback monitoring |
+
+## Billing model (affects every service)
+
+- Requests are paid from the **wallet** (per request) or from a **subscription** (monthly: 30 days no rollover; annual: 365 days, any pace). Both can coexist; the wallet is the fallback when subscription requests run out.
+- Some APIs have free daily/monthly tiers; rate limits, when present, are stated in each API's description.
+- **Sandbox**: free test requests, but "sandbox credit" must be enabled in the console first; responses are illustrative.
 
 ## Notes
 
 - OAuth v1 (`oauth.openapi.it`) is deprecated — always use `oauth.openapi.com`.
-- Sandbox testing requires enabling "sandbox credit" in the console first; see [platform guide](../../knowledge/platform-guide.md).
-- Full spec: [knowledge/oas/oauthv2.openapi.json](../../knowledge/oas/oauthv2.openapi.json) · endpoint list: [knowledge/services/oauthv2.md](../../knowledge/services/oauthv2.md)
+- Service health: https://openapi-com.statuspage.io
+- Full spec: https://console.openapi.com/oas/en/oauthv2.openapi.json

skills/openapi-automotive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openapi-automotive
-description: Vehicle data through Openapi Automotive - look up cars, motorcycles and insurance status by license plate (Italian and European). Use for "whose car is this plate", vehicle technical data, insurance validity checks.
+description: Vehicle data through Openapi Automotive - look up cars, motorcycles, insurance and MOT status by license plate across Italy, UK, Germany, France, Spain, Portugal. Use for vehicle technical data and insurance validity checks by plate.
 ---
 
 # Openapi Automotive
@@ -9,16 +9,26 @@ Base URL: `https://automotive.openapi.com` — vehicle information by license pl
 
 Authentication: Bearer token — see the `openapi-auth` skill.
 
-## Endpoints (14 — see reference for the full list)
+## Endpoints
 
-- Cars: vehicle technical data by plate
-- Motorcycles: same for two-wheelers
-- Insurance: check insurance coverage status of a plate
+| Country | Endpoints |
+|---|---|
+| Italy | `GET /IT-car/{plate}` · `GET /IT-bike/{plate}` · `GET /IT-insurance/{plate}` |
+| United Kingdom | `GET /UK-car/{plate}` · `GET /UK-bike/{plate}` · `GET /UK-mot/{plate}` |
+| Germany | `GET /DE-car/{KBANumber}` (KBA number, not plate) |
+| France | `GET /FR-car/{plate}` · `GET /FR-bike/{plate}` |
+| Spain | `GET /ES-car/{plate}` · `GET /ES-bike/{plate}` |
+| Portugal | `GET /PT-car/{plate}` · `GET /PT-insurance/{plate}` |
 
-## Sandbox
+Async requests can be checked with `GET /check_id/{id}`.
+
+```bash
+curl -s https://automotive.openapi.com/IT-car/AB123CD \
+  -H "Authorization: Bearer $OPENAPI_TOKEN"
+```
 
-A dedicated sandbox simulates requests with test plates — use it to validate integrations before paying for real lookups.
+## Sandbox
 
-## References
+The sandbox returns predefined dummy data for test plates (or KBA numbers for Germany) — validate integrations there before paying for real lookups.
 
-Full spec: [knowledge/oas/automotive.openapi.json](../../knowledge/oas/automotive.openapi.json) · endpoint list: [knowledge/services/automotive.md](../../knowledge/services/automotive.md)
+Full spec: https://console.openapi.com/oas/en/automotive.openapi.json

skills/openapi-company/SKILL.md

@@ -1,29 +1,39 @@
 ---
 name: openapi-company
-description: Look up company/business data through Openapi - Italian companies by VAT/tax code or name, European and worldwide company search, legal forms, company credit scores. Use for questions like "find data about company X", "who owns VAT number Y", "search companies in France/EU/worldwide".
+description: Look up company/business data through Openapi - Italian companies by VAT/tax code or name, European and worldwide company search, shareholders, UBO, AML, PEC/SDI codes, company monitoring. Use for questions like "find data about company X", "who owns VAT number Y", "search companies in France/EU/worldwide".
 ---
 
 # Openapi Company data
 
 Base URL: `https://company.openapi.com` — company master data from official registers (Chamber of Commerce, CRIF, INPS and more).
 
-Authentication: Bearer token with `company.openapi.com` scopes — see the `openapi-auth` skill.
+Authentication: `Authorization: Bearer <token>` with `company.openapi.com` scopes — see the `openapi-auth` skill.
 
-## Choosing the right endpoint
+## Italian companies (by VAT or tax code)
 
-| Need | Endpoint |
+| Endpoint | Returns |
 |---|---|
-| Quick Italian company lookup (cheap) | `GET /IT-start/{vat_or_taxcode}` |
-| Full Italian company report | `GET /IT-full/{vat_or_taxcode}` |
-| Advanced Italian data (async) | `GET /IT-advanced/{id}` after starting a request |
-| Search Italian companies by name/filters | `GET /IT-search` |
-| Italian legal forms list | `GET /IT-legalforms` |
-| French companies | `GET /FR-search` |
-| Other EU countries (async start/advanced) | `EU-start` → `EU-advanced` |
-| Worldwide (async) | `WW-start` → `WW-advanced`; quick top-level: `WW-top` |
-| Credit score (top-level) | see `risk` service (`openapi-risk` skill) |
-
-The async pattern (start → poll advanced with the returned `id`, or pass a `callback` URL) is described in the [platform guide](../../knowledge/platform-guide.md#async-request-pattern).
+| `GET /IT-start/{vatCode_taxCode_or_id}` | Basic data (cheap, start here) |
+| `GET /IT-advanced/{vatCode_taxCode_or_id}` | Advanced data |
+| `GET /IT-full/{vatCode_or_taxCode}` | Everything (most expensive) |
+| `GET /IT-search` | Search by name/filters |
+| `GET /IT-shareholders/…` / `GET /IT-ubo/…` | Shareholders / ultimate beneficial owners |
+| `GET /IT-aml/…` | Anti-money-laundering data |
+| `GET /IT-pec/…` / `GET /IT-sdicode/…` | Certified e-mail / SDI invoicing code |
+| `GET /IT-address/…`, `/IT-name/…`, `/IT-closed/…`, `/IT-vatgroup/…`, `/IT-splitpayment/…`, `/IT-pa/…` | Address, name, activity cessation, VAT group, split payment, public administration |
+| `GET /IT-legalforms` | Italian legal forms list |
+| `GET /IT-check_id/{id}` | Status of an async request |
+
+POST variants of `/IT-full`, `/IT-aml`, `/IT-marketing`, `/IT-stakeholders` run asynchronously: pass a `callback` URL or poll `GET /IT-check_id/{id}`.
+
+## Other countries
+
+- Dedicated start/advanced pairs: `FR` (also `/FR-search`), `DE`, `ES`, `PT`, `GB`, `BE`, `AT`, `CH`, `PL` — e.g. `GET /FR-start/{siret_siren_or_vat}`.
+- Worldwide: `GET /WW-start/{country}/{id}`, `GET /WW-advanced/{country}/{id}`, `GET /WW-top/{country}/{id}`.
+
+## Monitoring
+
+`POST /monitor` registers a company for change notifications; `GET /monitor`, `GET/DELETE /monitor/{id}` manage registrations.
 
 ## Example
 
@@ -34,5 +44,6 @@ curl -s https://company.openapi.com/IT-start/12485671007 \
 
 ## Notes
 
-- The legacy `imprese.openapi.it` API offers similar Italian lookups; prefer `company.openapi.com`. Sandbox test VAT numbers: https://docs.openapi.it/imprese-sandbox-examples.html
-- Full spec: [knowledge/oas/company.openapi.json](../../knowledge/oas/company.openapi.json) · endpoints: [knowledge/services/company.md](../../knowledge/services/company.md) · legacy: [knowledge/services/imprese.md](../../knowledge/services/imprese.md)
+- Sandbox test companies: https://docs.openapi.it/company-sandbox-examples.html
+- The legacy `imprese.openapi.it` API offers similar Italian lookups; prefer `company.openapi.com`.
+- Full spec: https://console.openapi.com/oas/en/company.openapi.json

skills/openapi-documents/SKILL.md

@@ -1,31 +1,37 @@
 ---
 name: openapi-documents
-description: Obtain official Italian documents through Openapi - chamber of commerce reports (visure camerali), financial statements/balance sheets, company files (fascicoli), bylaws, DURC, protest reports, cadastral documents. Use when the user needs an official PDF document about an Italian company or person.
+description: Obtain official Italian documents through Openapi - chamber of commerce reports (visure camerali), financial statements/balance sheets, company files (fascicoli), bylaws, DURC, protest reports. Use when the user needs an official PDF document about an Italian company or person.
 ---
 
 # Openapi official documents
 
-Three services deliver official documents; all are **asynchronous** (request → poll → download PDF).
+Two main services deliver official documents; both are **asynchronous** (request → poll → download PDF) and **paid per document** — check wallet credit (`openapi-auth` skill) and confirm with the user before bulk requests.
 
-| Service | Base URL | Use for |
-|---|---|---|
-| DocuEngine (preferred) | `https://docuengine.openapi.com` | All documents: Business Register, Revenue Agency, Municipalities, INPS (DURC), protests, balance sheets |
-| Visure Camerali | `https://visurecamerali.openapi.it` | Chamber of commerce registrations and financial statements |
-| Visengine (legacy) | `https://visengine2.altravia.com` | Older engine for the same document families |
+## DocuEngine (preferred) — `https://docuengine.openapi.com`
 
-Authentication: Bearer token — see the `openapi-auth` skill.
+Official documents from the Business Register, Revenue Agency, Municipalities and INPS, behind one uniform API:
 
-## DocuEngine workflow
+1. `GET /documents` — list available document services (codes, prices).
+2. `POST /requests` — create a request with the service code and subject (VAT/tax code); optionally pass a `callback` URL.
+3. `GET /requests/{id}` — poll until the request state is fulfilled (`EVASA`).
+4. `GET /requests/{id}/documents` — download the resulting documents.
+5. `PATCH /requests/{id}` — update a request when the service asks for it (e.g. optical balance-sheet processing).
 
-1. `GET /services` — discover available document types and prices.
-2. `POST /documents` with the service code and subject (VAT/tax code) — returns a request `id`. Optionally pass a `callback` URL.
-3. `GET /documents/{id}` — poll status until the document is ready.
-4. Download the PDF from the returned URL/payload.
+Document families: visura camerale (ordinaria/storica, per company type, also in English), fascicolo società (current/historical), bilancio (XBRL, ottico, riclassificato), statuto, certificato di iscrizione, certificato artigiano, DURC online, visura protesti and pregiudizievoli (companies and natural persons), cariche/quote/soci attivi, eventi negativi, atto ottico.
 
-Document families include: visura camerale (ordinaria/storica, by company type), fascicolo (company file, current/historical), bilancio (XBRL, ottico, riclassificato), statuto (bylaws), certificato di iscrizione, DURC online, protesti and pregiudizievoli (companies and persons), cariche/quote/soci (offices, shares, shareholders), eventi negativi.
+## Visure Camerali — `https://visurecamerali.openapi.it`
+
+Direct chamber-of-commerce endpoints, one resource per document type, all with the same pattern `POST /<type>` → `GET /<type>/{id}` → `GET /<type>/{id}/allegati` (download):
+
+- `ordinaria-impresa-individuale`, `storica-impresa-individuale`
+- `ordinaria-societa-capitale`, `storica-societa-capitale`
+- `ordinaria-societa-persone`, `storica-societa-persone`
+- `bilancio-ottico`, `certificato-iscrizione`, `certificato-iscrizione-vigenza`, …
+- Company search first: `GET /impresa?...` or `GET /impresa/{cf_piva_id}` to identify the subject.
+
+Visengine (`https://visengine2.altravia.com`) is the older engine for the same families — prefer DocuEngine for new work.
 
 ## Notes
 
-- These calls are **paid per document** — check wallet credit first (`openapi-auth`) and confirm with the user before bulk requests.
-- Sandbox responses are illustrative; enable sandbox credit first.
-- Specs: [docuengine](../../knowledge/oas/docuengine.openapi.json) · [visurecamerali](../../knowledge/oas/visurecamerali.openapi.json) · [visengine](../../knowledge/oas/visengine.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
+- Sandbox responses are illustrative; enable sandbox credit in the console first.
+- Full specs: https://console.openapi.com/oas/en/docuengine.openapi.json · https://console.openapi.com/oas/en/visurecamerali.openapi.json · https://console.openapi.com/oas/en/visengine.openapi.json

skills/openapi-esignature/SKILL.md

@@ -1,25 +1,38 @@
 ---
 name: openapi-esignature
-description: Digital signatures and time stamps through Openapi - eIDAS-compliant electronic signature workflows (eSignature) and qualified time stamping of documents (Marche Temporali). Use when the user needs a document signed electronically or time-stamped with legal validity.
+description: Digital signatures and time stamps through Openapi - eIDAS-compliant electronic signatures (SES with OTP, qualified QES, e-seals, massive automatic signing) and qualified time stamping of documents. Use when the user needs a document signed electronically or time-stamped with legal validity.
 ---
 
 # Openapi eSignature & time stamping
 
 Bearer token required (see the `openapi-auth` skill). Signing and stamping are paid, legally binding actions — confirm with the user before submitting documents.
 
-| Service | Base URL | Use for |
-|---|---|---|
-| eSignature | `https://esignature.openapi.com` | eIDAS-compliant signature processes (simple to qualified), signer invitations, signed-document retrieval |
-| Time Stamping | `https://ws.marchetemporali.com` | Purchase qualified timestamps and apply them to documents |
+## eSignature — `https://esignature.openapi.com`
 
-## eSignature workflow (typical)
+eIDAS-compliant signatures with European legal validity.
 
-1. Create a signature process/envelope with the document (PDF) and signer details.
-2. Signers receive an invitation and sign according to the configured signature level.
-3. Track process status (webhooks/polling) and download the signed document when complete.
+### Signature types
 
-Legacy **Digital Signature** (`ws.firmadigitale.com` — Infocert/Aruba kits, digital identities) is **deprecated**; use eSignature for new integrations.
+- `POST /EU-SES` — Simple Electronic Signature for one or more signers, secured via OTP
+- `POST /EU-QES_otp` — Qualified Electronic Signature with remote OTP certificate
+- `POST /EU-QES_automatic` — massive automatic QES (high volume)
+- `POST /EU-QES_eseal` — qualified electronic seal (legal-entity seal)
+- `POST /verify` — verify an existing signature
 
-## References
+### Certificates and results
 
-Specs: [esignature](../../knowledge/oas/esignature.openapi.json) · [marchetemporali](../../knowledge/oas/marchetemporali.openapi.json) · legacy [firmadigitale](../../knowledge/oas/firmadigitale.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
+- `POST /certificates/namirial-otp` / `POST /certificates/namirial-automatic` — purchase signing certificates
+- `GET /certificates`, `GET /certificates/{id}` — list/inspect certificates
+- `GET /signatures` — list signature processes
+- `GET /signatures/{id}/{actionType}` — download the signed document, details, audit trail, or validated document
+- `DELETE /signatures/{id}` — delete signature artifacts
+
+Typical flow: ensure a certificate exists → create the signature request with the PDF and signer details → signers complete via OTP where applicable → download the signed document and audit trail.
+
+## Time Stamping (Marche Temporali) — `https://ws.marchetemporali.com`
+
+Purchase qualified timestamps and apply them to documents (buy batches, stamp a document, verify stamps).
+
+Legacy **Digital Signature** (`ws.firmadigitale.com` — Infocert/Aruba kits) is **deprecated**; use eSignature for new integrations.
+
+Full specs: https://console.openapi.com/oas/en/esignature.openapi.json · https://console.openapi.com/oas/en/marchetemporali.openapi.json