agentic

Source: https://ruagentic.org/docs/ABOUT.md

# About Agentic

Agentic is an open file convention that helps agents find a website's documentation, APIs, and agent connections, and describes how supporting clients can verify completed actions.

`agentic.json` contains structured information. Its generated `agentic.txt` provides a readable index. The [generator](https://ruagentic.org/generate/) reads public sources and produces the pair. JSON remains authoritative.

[Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md) describes discovered resources and documented operations. [Action Profile 1.0](https://ruagentic.org/docs/SPEC.md) defines request tracking and result checks for services that implement its contract. A website can publish a site profile without implementing action recovery. Files do not create endpoints, grant authorization, or automatically add support to every agent.

Maintained by [sam1siam](https://github.com/sam1siam), the specification, schemas, and tools are Apache-2.0. Tools 1.3.0 support both profile types. Install [ruagentic from npm](https://www.npmjs.com/package/ruagentic), use the CLI or browser tools, or contribute in the [repository](https://github.com/sam1siam/agentic).

## What the website runs

The website scanner and auditor read public HTTPS documents on the server. The advanced manual builder and OpenAPI importer run locally in the browser. The recovery service uses isolated synthetic ticket data; our root Agentic files describe that service. MCP, conditional WebMCP, A2A and Agent Auth connections are documented in [Protocol setup](https://ruagentic.org/docs/PROTOCOLS.md).

Reports are private to a browser session or agent owner and expire after 30 days. Share a report only through the explicit sharing controls. See [platform operations](https://ruagentic.org/docs/PLATFORM.md).

No enrollment or central registry is required. Report reproducible bugs, propose improvements, or submit focused pull requests. [Governance](https://ruagentic.org/docs/GOVERNANCE.md), [security](https://ruagentic.org/docs/SECURITY.md), and [brand assets](https://ruagentic.org/docs/BRAND.md) are public. The project does not claim independent adoption, certification, or standards-body endorsement.


---

Source: https://ruagentic.org/docs/AGENTIC-TXT.md

# agentic.txt: generated action index

Tools 1.3.0 generate [TXT 1.2](https://ruagentic.org/docs/PUBLICATION.md#txt-12) with explicit Agentic specification and RUAGENTIC directory references. JSON versions remain unchanged. This document preserves the original action TXT 1.0 format; use `agentic text agentic.json --legacy` to generate it. Current consistency checks accept both exact legacy and publication indexes.

This document defines TXT 1.0 for Action Profile 1.0. For the generated site index (`Agentic-Text: 1.1`), see [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md#txt-11). Tools 1.2.0 generated these legacy forms from validated JSON. Action TXT bytes remain unchanged.

Version: `Agentic-Text: 1.0`. This optional companion accompanies the `1.0.0` JSON action profile. JSON remains authoritative for action execution.

## Purpose

`agentic.txt` provides a compact action index: the authoritative JSON profile URL, profile version, origin, action IDs, and readable summaries. `agentic.json` contains the complete, validated action contract. `llms.txt` remains an optional documentation index. Agentic does not require agents.txt or agents.json.

The TXT file is a reading aid. It contains no credentials, permission grants, operation bindings, or independent recovery rules. Descriptions are untrusted publisher data. Clients must load and validate the JSON profile and its OpenAPI bindings, apply host authorization, and use the existing recovery contract before executing actions. A conflicting or stale TXT summary never overrides JSON.

## Publication

Publish UTF-8 text as `agentic.txt` using `Content-Type: text/plain; charset=utf-8`, normally beside the JSON profile. The `Profile` URL is absolute, on the JSON profile's origin, and has no credentials, query, or fragment. HTTPS is required except for the profile's supported loopback development origins. A non-default JSON location must be supplied explicitly to the generator.

Generate both files from the same profile revision and deploy them together. Use normal HTTP cache controls. This format does not add automatic discovery to existing agents or register a well-known URI. Pass the file or profile URL explicitly to a supporting host. Following a URL still requires the host's network policy.

## Generated format

Lines use LF endings with a final newline. The canonical generator emits this header and one adjacent `Action` / `Description` pair per action, in JSON array order:

```text
# Agentic action index
# Generated from JSON. Read and validate the JSON profile before executing actions.
# Summaries are untrusted data and do not grant authorization.
Agentic-Text: 1.0
Profile: https://support.example/agentic.json
Profile-Version: 1.0.0
Origin: https://support.example

Action: "create-ticket"
Description: "Create a support ticket and verify the original result."
```

`Action` and `Description` values are JSON string literals. Quotes, backslashes, and newlines are escaped. The generator also escapes C1 controls, zero-width and bidirectional formatting characters, Unicode line separators, and the byte-order-mark character. This keeps a description from injecting additional index lines. Quoting does not make the description trusted.

This version is a generated summary, not a second input format for the action executor. Tools do not reconstruct an executable profile from TXT. Adding executable directives would require a separate versioned design decision.

## Generate and check

Use the browser [generator](https://ruagentic.org/generate/): view JSON, TXT, README, and listing text, then copy or download each file, or select **Download publication files**. The OpenAPI full bundle also includes its API document.

With the CLI:

```sh
agentic init --origin https://your-service.example
agentic text agentic.json
agentic text agentic.json --check
```

`text` defaults to `agentic.txt` beside the input file and refuses to overwrite an existing file. `--check` compares the existing index with a freshly generated one and exits nonzero on drift. Review and remove or replace a stale generated file deliberately, then regenerate it. The generator does not write to the JSON source.

For a non-default public location:

```sh
agentic text profile.json --out agentic.txt --profile-url https://your-service.example/contracts/profile.json
```

From a source checkout, use `npm run text -- agentic.json` with the same options. MCP and WebMCP profile-generation results include a `files` object containing JSON, TXT, README, and listing text.

For an explicit loopback development profile, add `--allow-local`. This permits HTTP only on localhost, 127.0.0.1, or [::1]; production profiles still require HTTPS. The local reference server serves its matching TXT at `/agentic.txt` automatically.

## Live and illustrative examples

- [Live agentic.txt](https://ruagentic.org/agentic.txt) and [live agentic.json](https://ruagentic.org/agentic.json) describe this project's authenticated synthetic ticket service.
- [Illustrative TXT](https://ruagentic.org/examples/tickets/agentic.txt) and [illustrative JSON](https://ruagentic.org/examples/tickets/agentic.json) use `support.example`; those URLs are placeholders to replace on your own service.

The public JSON/TXT files describe the synthetic service; publishing them does not grant access to it. The paired files do not establish independent adoption, service certification, or universal agent support.


---

Source: https://ruagentic.org/docs/AUDIT.md

# Audit your Agentic publication

Enter your website or full agentic.json URL in [the auditor](https://ruagentic.org/audit/). It checks the JSON, linked API/documents, matching agentic.txt, and README.md. The result explains what passed, what is missing, and how to fix each issue.

## Results

- **Successful:** the JSON/API checks, TXT consistency, and README/file/reference link checks passed.
- **Partial:** the JSON/API checks passed, but optional companion files, project references, content types, or remaining document checks need attention.
- **Failed:** JSON/API checks failed, TXT conflicts with JSON, or README links point to different Agentic files.

Every issue includes a concrete remedy, such as the exact file URL to publish, a Markdown link to add, or the API binding to correct. The checker reports TXT and README availability even when agentic.json is missing.

## README location and content

By default the checker reads README.md beside agentic.json, then tries lowercase readme.md after a 404. Expand **README hosted elsewhere?** to enter a public raw Markdown URL. For GitHub, use the Raw URL rather than an HTML repository page. Use README.md as the filename; README.me is a typo the checker will flag when supplied.

The README may contain customized prose. Checks look for visible links to the exact JSON/TXT locations, ruagentic.org, and ruagentic.com. Fenced code, inline code and HTML comments do not count. README links are inspected without being fetched. The checker does not verify every claim or confirm directory acceptance.

## JSON and API scope

Both Site Profile 1.1.0 and Action Profile 1.0.0 are supported. Site audits check structure, serving origin, matching TXT, and up to five retrieved same-origin documents, prioritizing indexed APIs. Action audits check the JSON and up to five referenced OpenAPI binding documents. An advertised MCP link is not invoked; that informational boundary does not prevent a successful file audit.

The auditor accepts exact legacy TXT 1.0/1.1 or publication TXT 1.2. JSON is limited to 64 KiB, README/TXT to 64 KiB each, action OpenAPI documents to 256 KiB, and site documents to 1 MiB each. Reads use public-only HTTPS, pinned DNS/IP checks, no redirects or forwarded credentials, and bounded timeouts. The auditor never fetches arbitrary schema URLs or submits service actions.

## Reports and CLI

Report version 3 retains `valid` for JSON/API checks and adds `readme` and `publication`. Missing README/TXT does not by itself make JSON invalid. Require `publication.status === "successful"` to enforce a complete publication, or `valid && textIndex.status === "matched"` to require only the pair. README references are recommendations, not protocol authorization requirements.

```sh
npm install -g ruagentic@1.3.0
agentic audit https://your-site.com
agentic audit https://your-site.com --publication
agentic audit https://your-site.com --readme https://raw.example/repo/README.md --publication
```

The default exit code preserves JSON/API validity. `--publication` exits nonzero for partial or failed publication. Hosted MCP exposes the same report through `audit_agentic_url`, with optional `readmeUrl`. Reports are private to the caller and retained for up to 30 days.

Use [Generate](https://ruagentic.org/docs/GENERATOR.md) to create all files. [Publication details](https://ruagentic.org/docs/PUBLICATION.md) describe the versions, exact TXT references, README merging, and listing copy. A successful file audit is not a runtime test, security certification, or endorsement.


---

Source: https://ruagentic.org/docs/BRAND.md

# Agentic identity

The mark places a capital A between two JSON-style braces, the same {A} mark used by the RUAGENTIC directory. The wordmark is `agentic.json`, set in a monospace face. The project name remains **Agentic**, and its home is **ruagentic.org**.

## Assets

- [Mark, transparent SVG](https://ruagentic.org/brand/agentic-mark.svg)
- [Wordmark for dark surfaces](https://ruagentic.org/brand/agentic-wordmark-dark.svg)
- [Wordmark for light surfaces](https://ruagentic.org/brand/agentic-wordmark-light.svg)
- [Agentic profile badge](https://ruagentic.org/brand/profile-badge.svg)

These original project assets are included under the repository's Apache-2.0 license. The badge identifies use of Agentic; it must not be presented as certification or proof of conformance.

## Palette and typography

| Role              | Value                                                        |
| ----------------- | ------------------------------------------------------------ |
| Background        | #05080C                                                      |
| Glass surface     | white at 10% to 3.5% over the background, 1 px border at 14% |
| Text              | #F2F8FC                                                      |
| Body text         | #C9D6E2                                                      |
| Muted text        | #8FA6B6                                                      |
| Primary (sand)    | #FFB020 with #1A1200 text                                    |
| Accent (ice blue) | #5CE1E6                                                      |

The website uses Instrument Sans for prose and JetBrains Mono for code, labels and the wordmark, sharing the RUAGENTIC directory's styling with the two colours swapped: sand is the primary where the directory uses ice blue, and ice blue is the accent where the directory uses sand. Keep the mark legible at 24 px or larger, preserve its aspect ratio, and allow clear space around it. Use the dark wordmark on dark surfaces and the light version on light surfaces.

The developer-oriented presentation takes direction from [agent.json](https://www.agent-json.org/): dark surfaces, a single accent colour, monospace identity, and visible code examples. The Agentic mark and layout are original; no affiliation or endorsement is implied.


---

Source: https://ruagentic.org/docs/CHANGELOG.md

# Changelog

## Tools 1.3.0 / TXT 1.2 — 2026-09-08

- Generate README.md and portable LISTING.md text automatically with both Agentic files.
- Add versioned TXT 1.2 project references describing ruagentic.org and ruagentic.com; preserve Action Profile 1.0 and Site Profile 1.1 JSON and legacy TXT compatibility.
- Audit README availability, raw content, file links, and project references. Support an explicitly supplied raw README URL.
- Add publication results: successful, partial, or failed, with specific remedies and companion availability when JSON is missing.
- Add CLI bundle generation, legacy TXT output, optional README URL, and opt-in complete-publication exit codes.

## Tools 1.2.0 / Site Profile 1.1.0 — 2026-09-07

- URL-first generation reads public websites, documentation, llms.txt, OpenAPI JSON, and advertised agent connections, then outputs both Agentic files and a source report.
- Additive Site Profile 1.1.0 and TXT 1.1 describe resources and API indexes without inventing action-recovery behavior. Action Profile 1.0.0, receipts, and TXT 1.0 remain compatible.
- Public-only network checks, canonical redirects, bounded reads, deadlines, source provenance, and explicit partial-scan notes.
- CLI `discover`, MCP/WebMCP `discover_agentic_site`, site validation and auditing, plus a collapsed advanced action builder.
- Updated generator, specification, documentation, package contents, and compatibility tests.

## Tools 1.1.0 — 2026-09-07

- Simplified navigation: Generate, Spec, Audit, Compare, and About.
- Paired TXT and JSON previews, individual copy/download controls, and one ZIP containing both files. OpenAPI imports use the same paired view.
- Dedicated public audit with readable checks, downloadable reports, TXT consistency, and partial results when linked files fail.
- Website and directory URL normalization, explicit query rejection, exact content-type checks, and bounded concurrent file reads. Existing public-network, no-redirect, and size restrictions remain enforced.
- Clearer copy, responsive spacing, keyboard-accessible code panes, and Markdown alternatives for all thirteen pages.
- Profile and receipt version 1.0.0, schemas, and TXT 1.0 are unchanged. No format migration is required from tools 1.0.0.

See [audit report semantics](https://ruagentic.org/docs/AUDIT.md) for the distinction between JSON/API validity and TXT consistency.

## 1.0.0 — 2026-09-07

Agentic 1.0.0 publishes the action profile, supporting tools, and hosted services as a versioned release.

- Authoritative `agentic.json` profiles and optional generated `agentic.txt` action indexes, with `Agentic-Text: 1.0`.
- Versioned `agentic-1.0.schema.json` and `receipt-1.0.schema.json` schemas for validation, OpenAPI operation binding, and verified outcome receipts.
- CLI generation, validation, public URL auditing, JSON/TXT consistency checks, and local MCP tools.
- Browser JSON/TXT generation and downloads, OpenAPI starter bundles, validation, and a recovery simulation.
- Hosted HTTP/PostgreSQL recovery checks, private report history and sharing, MCP, A2A, WebMCP page hooks, and Agent Auth verification.
- Node and Python consumers, a local HTTP/SQLite service, a compatibility runner, a GitHub Action, and an integration skill.
- Updated documentation, installation instructions, package metadata, and public release terminology.

Use profiles that declare `"agentic": "1.0.0"` with the 1.0 schemas and tools. When updating an existing integration, regenerate its TXT index and rerun profile, binding, and behavioral checks. Follow the [migration guide](https://ruagentic.org/docs/MIGRATION.md) to update profile and receipt identifiers for new work while retaining the original snapshots and installed compatible clients for unfinished requests. Do not relabel a saved in-flight request or repeat its write during migration.

Compatibility evidence applies to the exact versions and scenarios recorded by each run. This release does not relabel earlier measurements as 1.0.0 results. See [GitHub releases](https://github.com/sam1siam/agentic/releases/tag/v1.0.0) for versioned artifacts and release verification.


---

Source: https://ruagentic.org/docs/COMPARE.md

# Where Agentic fits

Agentic provides a structured site profile and an optional action-recovery contract. It works with existing documentation and protocols.

| Format | Purpose | Relationship to Agentic |
| --- | --- | --- |
| [llms.txt](https://llmstxt.org/) | Documentation context and links. | The generator reads it as a source; keep it as a documentation index. |
| [AGENTS.md](https://agents.md/) | Instructions for coding agents in a repository. | Continue using it for setup, tests, and conventions. |
| [agents.txt / agents.json](https://agents-txt.com/spec/) | Website capability and protocol declarations. | Site discovery overlaps. Agentic has its own schema and additionally defines a separate action-recovery contract; neither convention is required by the other. |
| [OpenAPI](https://spec.openapis.org/oas/latest.html) | HTTP operations, parameters, responses, and authentication. | Site profiles index documented operations; action profiles bind a supported OpenAPI 3.1 subset. The API description remains authoritative. |
| [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) | Tool and resource access for AI applications. | Site profiles can list advertised MCP URLs. Agentic's scanner never invokes discovered tools. |

`agentic.txt` is generated from `agentic.json` and links back to it. A site profile lists resources and API operations. An action profile defines submission, status lookup, result evidence, and bounded recovery. Neither profile grants authorization or installs protocol support.

Start with the [generator](https://ruagentic.org/generate/) and [specification](https://ruagentic.org/spec/). See [prior work](https://ruagentic.org/docs/PRIOR-ART.md) for related techniques and specifications.


---

Source: https://ruagentic.org/docs/COMPATIBILITY.md

# External-client compatibility runner

This runner gives separately written clients the same synthetic ticket service and seven behavior scenarios. It checks outcomes and observes HTTP calls and persisted resources. It does not certify the implementation or prove independent authorship.

## Run the reference adapter

From the repository root, after the [quick start](https://ruagentic.org/docs/QUICKSTART.md) installation:

```sh
npm run conformance -- --adapter integrations/node-reference.json
```

To retain a report, create a private output directory and pass `--out path/to/report.json`. Add `--revision YOUR_IMPLEMENTATION_COMMIT` when submitting evidence. The example adapter is project-authored; its passing report is not independent adoption.

## Connect your implementation

Create a local JSON configuration, for example:

```json
{
  "name": "Your independently written client",
  "authorship": "external-self-declared",
  "command": ["python", "/absolute/path/to/your_adapter.py"]
}
```

`command` is a locally trusted executable and argument array, not a shell string or a value obtained from a remote manifest. The process runs with the repository root as its current directory. The harness launches a fresh loopback service and temporary ledger directory per scenario. It never points at production.

The adapter reads one JSON object from stdin:

| Key | Meaning |
| --- | --- |
| profile | Full Agentic profile, with an explicit `http://127.0.0.1:PORT` test origin |
| openapi | The matching OpenAPI 3.1 document |
| request_id | Identity to persist and use throughout the attempt |
| input | Synthetic ticket input |
| ledger_path | A temporary persistent location shared across restart calls |
| test_crash_after_submit | Test hook: terminate with exit code 86 after the submission has been attempted and before reconciliation |

In normal execution, write exactly one receipt JSON object to stdout and exit zero, including for a valid `unknown` or `pending` receipt. Put diagnostic logs on stderr. For the crash hook, exit 86 without a receipt. Never implement this test hook in an untrusted production request interface.

You may use a different persistence format at `ledger_path`; treat it as a per-scenario namespace. When invoked again with the same location and request identity, resume the saved attempt without another POST. Preserve host permission and origin policy in your actual integration; the harness is deliberately local and single-principal.

Run:

```sh
npm run conformance -- --adapter /path/to/adapter.json --revision YOUR_COMMIT --out report.json
```

## Scenarios

| Scenario | Expected result |
| --- | --- |
| normal | One resource; verified success |
| response-lost | One resource despite a dropped reply; verified success |
| status-unavailable | One committed resource, unknown outcome, no repeated write |
| stale-read | An initially missing resource becomes readable; verified success |
| wrong-evidence | Mismatched request evidence produces unknown |
| pending | Pending receipt, zero resources |
| restart-after-submit | Process exits after committing the submission; a new process recovers without another POST |

Each case checks receipt structure, request/action/origin identity, a single submission, status lookup, and expected resource count. Successful cases also check resource reads and evidence identity, source, state, input bindings, and stored input. `--scenario normal` runs just that case for adapter debugging.

## Submit evidence

Use the repository's implementation-report issue form. Include your source repository, tested revision, adapter interface, report, provenance, and comparison against the existing workflow. Redact private information before uploading anything. Maintainers must review independence and reproducibility before adding a verified independent entry.

## Limits

The runner does not test production authentication, principal isolation, distributed leases, provider retention over real days, malicious destination policy, all malformed inputs, or all process-crash timings. A client can pass these examples and still violate other requirements. The broader project tests and manual integration review remain necessary. Self-declared external authorship is always recorded with `independence_verified: false`; the harness never awards adoption status automatically.


---

Source: https://ruagentic.org/docs/CONFORMANCE.md

# Conformance and measurement
This guide describes the project-run test suite and the evidence required for compatibility claims.

## Separate the claims
1. Schema-valid: a profile has the required shape and supported version.
2. Binding-valid: its operation references satisfy the limited OpenAPI binding.
3. Behavior-tested: named client/service versions pass specified failure scenarios.
4. Independently implemented: a separate team has implemented the profile and published its own results.

The web validator checks the first two when an OpenAPI document is supplied. It performs no endpoint calls. The browser lab uses the shared reference client algorithm against an in-memory simulated service; it does not create actual support tickets or persist browser state.

## Reproduce
Use Node 24 and Python 3.11 or later. Install the repository's npm dependencies and reference/python/requirements.txt. Run npm test and npm run benchmark.

Tests exercise committed-write response loss, stale reads, unavailable status, incorrect resource identity, pending outcomes, expired ledgers, changed-input key reuse, unsafe operation references, actual loopback HTTP reply loss, concurrent service deduplication, and process termination followed by SQLite recovery in both languages.

Both consumers are authored in this project. Their agreement tests portability but does not count as two independent adopters.

## External-client runner
Run `npm run conformance -- --adapter integrations/node-reference.json` for seven real HTTP scenarios, including process restart. The [runner guide](https://ruagentic.org/docs/COMPATIBILITY.md) documents the process interface for separately implemented clients. The runner observes submissions, reads, receipts, and stored resource counts. It rejects a claimed success with no service interaction.

Compatibility results apply only to the implementation revision and profile version recorded by the run. The local runner covers a single-principal behavior subset and leaves independent authorship unverified for later review. Run it against your pinned checkout to produce current evidence.

## Hosted platform coverage

The hosted platform tests real HTTP recovery using PostgreSQL persistence and isolated sessions. Tests also exercise official MCP and A2A clients, autonomous Agent Auth registration and signed execution, replay rejection, and revocation. The public URL auditor checks files and operation bindings without executing the target service.

See [platform operations](https://ruagentic.org/docs/PLATFORM.md), [protocol scope](https://ruagentic.org/docs/PROTOCOLS.md), and the dated [project-run live verification record](https://ruagentic.org/reports/platform-live.json). These results apply to the tested versions and synthetic scenarios, not to arbitrary customer APIs.

## Benchmark
reports/benchmark.json is generated by scripts/benchmark.ts. It runs deterministic scenarios and reports ticket counts, duplicates, calls, and outcomes. Each strategy receives an isolated service with the same fault.

Baselines include:
- Blind retry: retries with a new ID.
- Idempotent retry: retries with the same ID and reports success from a successful HTTP response.
- Existing verification workflow: separately written orchestration that performs status and resource checks, without consuming an Agentic profile.
- Agentic: the profile-driven reference consumer.

A competent existing workflow is expected to match Agentic's reliability in this example. Any benefit from a shared profile is an interoperability and implementation-effort hypothesis, not a proven advantage in the benchmark.

No customer production workload, independent security audit, statistical reliability estimate, adoption number, token saving, or performance advantage is established. Deterministic runs are not independent random samples. Latency measurements from a browser simulation would not represent network performance, so none are advertised.

## Known gaps
- Strict duplicate-member detection in JSON text is not implemented.
- The Node consumer supports the documented binding subset. The Python consumer is a smaller implementation limited to the shipped ticket binding.
- Host authorization remains an integration obligation. The local reference service is anonymous and loopback-only; the hosted platform implements private sessions and agent isolation for synthetic tasks, not customer account delegation.
- Browser lab storage is deliberately ephemeral. Durable behavior is tested in the local SQLite implementations and the hosted PostgreSQL platform.
- Optional WebMCP tools are feature-detected. They require a supporting browser; their browser registry behavior has not been verified in a supported WebMCP context in this release.
- Arazzo mappings, an MCP tool for executing arbitrary customer actions, signed outcome receipts, and generalized automatic write retries are not implemented. The MCP servers provide developer tools; Agent Auth signs requests, not receipts. The hosted ledger uses PostgreSQL advisory locks, while the local reference ledger remains tied to its SQLite storage.


---

Source: https://ruagentic.org/docs/DEPLOYMENT.md

# GitHub, Vercel, and ruagentic.org
The website exports static HTML, JavaScript, schemas, examples and documentation. The hosted platform adds a Node 24 Vercel Function and a Neon PostgreSQL database. Its required secrets, migrations, direct-connection requirements, retention and cron setup are documented in [Platform operations](https://ruagentic.org/docs/PLATFORM.md). The browser lab remains a simulation; the HTTP/SQLite reference service remains a separate loopback application.

## Vercel
Import sam1siam/agentic into the intended Vercel account.
- Framework preset: Other.
- Root directory: repository root.
- Install command: npm ci.
- Build command: npm run build.
- Output directory: dist/client.
- Node.js: 24.x.
vercel.json contains static output settings, API rewrites and a daily cleanup cron. Vinext exports the frontend; `api/platform.ts` serves the runtime endpoints. Production secrets are configured in Vercel, not in the exported files.

Run npm test and npm run build before publishing changes. npm run build prepares public artifacts and exports the website. It does not run Python tests; CI runs those separately.

## Spaceship DNS
Keep the domain registered at Spaceship unless a registrar transfer is independently desired. Add ruagentic.org to the Vercel project's Domains settings, then use the exact DNS record values shown for that project.

Do not guess A records, CNAME targets, or verification tokens. Preserve existing email and unrelated records. Update only the records needed for the selected hostname after checking any existing web destination. Add www only if desired and configure its redirect deliberately.

Check Vercel's domain verification and TLS status, then verify the root page, /spec/, /lab/, /validate/, /adopt/, /schemas/agentic-1.0.schema.json, and the example downloads on the final domain.

The .openai/hosting.json file identifies an optional private Sites preview and is unrelated to Vercel DNS. It contains no credential.


---

Source: https://ruagentic.org/docs/EXAMPLES.md

# Ticket example

One synthetic record-creation action demonstrates the initial profile binding. The generated agentic.txt summarizes the JSON profile; its support.example links are placeholders. The [live index](https://ruagentic.org/agentic.txt) and [live JSON](https://ruagentic.org/agentic.json) describe the hosted synthetic service. See [the TXT guide](https://ruagentic.org/docs/AGENTIC-TXT.md).

- [Generated action index](https://ruagentic.org/examples/tickets/agentic.txt)
- [Complete profile](https://ruagentic.org/examples/tickets/agentic.json)
- [OpenAPI document](https://ruagentic.org/examples/tickets/openapi.json)
- [Illustrative receipt](https://ruagentic.org/examples/tickets/receipt.json)
- [Profile schema](https://ruagentic.org/schemas/agentic-1.0.schema.json)
- [Receipt schema](https://ruagentic.org/schemas/receipt-1.0.schema.json)

| Role | Operation ID | Endpoint |
| --- | --- | --- |
| Submit | createTicket | POST /tickets |
| Reconcile | getRequestStatus | GET /requests/{requestId} |
| Verify | getTicket | GET /tickets/{ticketId} |

The client uses `Idempotency-Key`, persists its request identity before sending, and correlates the resulting resource's ID, request ID, state, and subject. A successful HTTP submit response alone is insufficient for verified completion.

The receipt file is illustrative and does not record a real customer action. It includes a request identity, origin, observation timestamp, outcome, resource, and evidence pointer pairs.

Use [the generator](https://ruagentic.org/generate/) to customize the profile, [the validator](https://ruagentic.org/validate/) for structural checks, and [the recovery lab](https://ruagentic.org/lab/) to explore simulated failures. The [quick start](https://ruagentic.org/docs/QUICKSTART.md) runs a real local HTTP drop after a committed ticket.


---

Source: https://ruagentic.org/docs/FAQ.md

# Frequently asked questions

## Does the generator write a README and listing description?

Yes. Download README.md and LISTING.md with the Agentic files. They contain the service description, file and documentation links, and clear references to ruagentic.org and ruagentic.com. Merge them with your existing project information. They do not submit a directory listing. The audit checks the README and explains missing files, incorrect links, and next steps. [How publication works](https://ruagentic.org/docs/PUBLICATION.md).

## Can I generate files by entering my website URL?

Yes. The generator reads public docs, llms.txt, OpenAPI JSON, and advertised agent links, then generates a complete Site Profile 1.1.0 and its TXT index. It preserves an existing valid action contract. No action API is required for a site profile. Unavailable sources and scan limits appear in the report. [How generation works](https://ruagentic.org/docs/GENERATOR.md).

## Does this configure my MCP server or create API endpoints?

No. The files describe what your public sources advertise. A linked endpoint is not verified by invoking it, and publishing the files does not install a protocol or grant credentials.

## What is the current Agentic version?

The current action profile is 1.0.0; the current tools are 1.3.0. The specification, JSON Schemas, CLI, and supporting services are available for direct use. The [governance guide](https://ruagentic.org/docs/GOVERNANCE.md) describes version compatibility and changes.

## Will agents discover agentic.json automatically?

Only supporting clients can use the convention. Supply the profile URL explicitly to your supporting client. Publishing the file does not add runtime support to an arbitrary agent.

## What must my service implement?

Atomic principal-scoped request tracking and idempotency, one POST submission, authoritative request-status lookup, and a resource read with correlated evidence. Version 1.0 binds inline operations from an OpenAPI 3.1 document.

## How does this relate to other agent files?

Documentation indexes help agents find content. Capability manifests describe available integrations. Agentic defines a focused contract for reconciling an already attempted action and verifying its outcome. See [INTEGRATIONS.md](https://ruagentic.org/docs/INTEGRATIONS.md).

## Does the file authorize an action?

No. The host must authorize the action, approve destinations, control credentials, and isolate ledgers. A publisher's text is untrusted data.

## Does it guarantee exactly-once execution?

No. The service must enforce idempotency and truthful status. The client avoids automatic repeat writes and requires evidence before declaring success. An unavailable or inconsistent result can remain unknown.

## What happens after tracking expires?

Preserve unknown and use the host's reconciliation or handoff process. Expiry is not proof that a new mutation is safe.

## Can we use Agentic without joining a program?

Yes. The specification, generators, validator, CLI, and hosted tools are available directly. Feedback and contributions are optional.

## Can we keep our implementation private?

Use a sandbox and keep customer information, tokens, receipts, and ledgers private. Share only approved redacted evidence. Public attribution is optional; an unreviewable private implementation cannot be counted as publicly verified independent compatibility.

## Is there an npm package?

Yes. Install [ruagentic from npm](https://www.npmjs.com/package/ruagentic) with `npm install -g ruagentic@1.3.0`. The same package is available from [GitHub releases](https://github.com/sam1siam/agentic/releases/tag/v1.3.0). Use [Get started](https://ruagentic.org/docs/GETTING-STARTED.md) for generation and validation commands. Node 24 or newer is required.

## Does Agentic require other agent files?

No. The action contract is agentic.json plus its referenced OpenAPI document. agentic.txt is our optional generated action index; JSON remains authoritative. llms.txt is an optional documentation index. This site does not publish or generate agents.txt or agents.json. MCP, WebMCP, A2A, and Agent Auth use their documented connection paths.

## Are integrations with other protocols complete?

No standardized cross-project Agentic binding is claimed. The integration guide describes coexistence and integration paths. Public MCP, A2A testing tasks, and autonomous Agent Auth are implemented on the hosted platform. WebMCP page hooks require browser support. See [protocol setup](https://ruagentic.org/docs/PROTOCOLS.md) for the supported scope.


---

Source: https://ruagentic.org/docs/GENERATOR.md

# Generate Agentic files from a website

The download now includes **README.md** and **LISTING.md** alongside agentic.json and agentic.txt. TXT 1.2 and both Markdown files identify [Agentic](https://ruagentic.org) as the specification/tools project and [RUAGENTIC](https://ruagentic.com) as the official Agentic directory for agentic AI MCP servers and tools. Copy or download files individually, or choose **Download publication files**. [Publication guide](https://ruagentic.org/docs/PUBLICATION.md) explains README merging, listing text, legacy TXT compatibility, and the checker.

Enter your website URL in [the generator](https://ruagentic.org/generate/) and select **Generate files**. The server reads public documentation, llms.txt, OpenAPI JSON, and linked agent connection information. It generates `agentic.json`, `agentic.txt`, `README.md`, and `LISTING.md` from the sources it finds.

1. Enter a public HTTPS website, documentation page, or profile URL. A bare domain is accepted.
2. Review the discovered sources and API operation count. **Read** means the document was retrieved; **Linked** means a source advertised the URL. Linked MCP endpoints are not invoked.
3. Copy or download each file, or download all four in the publication ZIP. The report records sources, failed reads, limits, and observation time.
4. Publish agentic.json and agentic.txt at your site's root, usually from its `public` folder. For an existing contract at a nested URL, preserve its file location and TXT `Profile:` URL, or regenerate TXT for the destination with `--profile-url`. Run the [audit](https://ruagentic.org/audit/) after publishing.

For a website without an existing action contract, the generator produces [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md): site details, documentation and protocol links, and an index of documented API operations. A site without an API can still publish a site profile. Existing valid Action Profile 1.0 contracts are preserved with matching TXT.

The scanner does not invent ticket operations, request tracking, retention windows, or recovery guarantees. Public pages cannot establish those guarantees. Configure them only when implementing an [action contract](https://ruagentic.org/docs/SPEC.md).

## What the scan reads

Public HTML, Markdown/text, OpenAPI 3 JSON, llms.txt, existing Agentic JSON, and A2A/Agent Auth metadata. Selected same-origin documentation links are followed. Cross-origin links are listed without fetching them. Canonical www/non-www redirects are supported; private network addresses and other cross-origin redirects are rejected. JavaScript, login-protected pages, and YAML OpenAPI documents are not processed.

Each scan has limits: 22 HTTP attempts, five concurrent documents, 1 MiB per response, 8 MiB of response-body allowance, with failed reads charged their full allowance, and a 40-second deadline plus a bounded DNS lookup. A report explains limits reached and unavailable sources. The files describe the discovered public material; the scan is not a full-site crawl or a protocol conformance test. Review them when your site changes and regenerate as needed.

The browser creates a private session automatically; no API key or account setup is required. Saved reports expire after 30 days. The same scanner is available locally:

```sh
npm install -g ruagentic@1.3.0
agentic discover https://your-site.com --out agentic-files
agentic validate agentic-files/agentic.json
agentic text agentic-files/agentic.json --check
```

The output directory must be new. It contains `agentic.json`, `agentic.txt`, `README.md`, `LISTING.md`, and `discovery-report.json`. No remote source instructions are executed.

## Advanced: an action contract

Expand **Advanced: configure an action or import OpenAPI yourself** to use the manual builder or import OpenAPI. These tools run locally in the browser. Changing only the URL of the support-ticket example does not adapt it to another API.

The manual builder exposes the service origin, action name, OpenAPI path, submit/status/verify operation IDs, retention window, read path parameter names, result/request/state JSON Pointers, successful states, and one input/result comparison. The full action schema supports more actions and evidence pairs. Recovery defaults are three checks, a 100 ms delay, a 3000 ms request timeout, and no automatic repeat write.

The importer accepts an OpenAPI 3.1 JSON file up to 256 KiB. Select real POST submission, GET request-status, and GET result operations, then supply the behavior and evidence your service implements. Its full bundle includes both Agentic files, OpenAPI, README with an implementation checklist, and listing text. Validate the bindings and test service behavior before publishing.

The CLI's `agentic init --origin https://service.example` command remains an explicit ticket-contract starter. It does not scan a website. Use `discover` for automatic website generation.

## Optional llms.txt

The separate llms.txt builder creates a documentation index locally. Edit its links to match your published pages. Agentic does not generate or require agents.txt or agents.json. [Protocol setup](https://ruagentic.org/docs/PROTOCOLS.md) explains the project's MCP, WebMCP, A2A, and Agent Auth services.


---

Source: https://ruagentic.org/docs/GETTING-STARTED.md

# Get started with Agentic

The generator includes README.md and portable LISTING.md text automatically. Merge README sections into your project documentation and publish a raw copy beside the Agentic files, or provide its URL when auditing. The audit reports successful, partial, or failed publication with specific remedies. [Publication guide](https://ruagentic.org/docs/PUBLICATION.md).

## Generate and publish

1. Open [Generate](https://ruagentic.org/generate/), enter your website URL, and choose **Generate files**.
2. Review the documentation, APIs, and advertised agent connections found by the scan.
3. Download the publication files. Publish JSON and TXT at `/agentic.json` and `/agentic.txt`; merge the generated README and use LISTING.md for directory descriptions.
4. Run the [public audit](https://ruagentic.org/audit/) after publishing.

The [site profile](https://ruagentic.org/docs/SITE-PROFILE.md) works with public documentation even when no API is available. To implement request recovery, use an [action contract](https://ruagentic.org/docs/SPEC.md) and the [integration guide](https://ruagentic.org/docs/INTEGRATIONS.md). Its operations and behavior must match your service.

## Install the CLI

Node 24 or newer is required.

```sh
npm install -g ruagentic@1.3.0
agentic discover https://your-site.com --out agentic-files
agentic validate agentic-files/agentic.json
agentic text agentic-files/agentic.json --check
```

The new output directory contains agentic.json, agentic.txt, README.md, LISTING.md, and a discovery report. Publish the pair, then run:

```sh
agentic audit https://your-site.com/agentic.json
```

`agentic text` regenerates TXT from either supported JSON type. `--check` detects drift. The separate `agentic init --origin https://service.example` command creates a ticket-contract starter requiring manual adaptation. Validate that action contract with `agentic validate agentic.json openapi.json`.

The package and checksums are available in the [GitHub release](https://github.com/sam1siam/agentic/releases/tag/v1.3.0).

## Add validation to GitHub Actions

After checking out your repository:

```yaml
- uses: sam1siam/agentic@v1.3.0
  with:
    profile: agentic.json
```

For an action profile, also set `openapi: openapi.json` to check its operation bindings. The [agent skill](https://github.com/sam1siam/agentic/releases/download/v1.3.0/agentic-adoption-skill.zip) guides a coding agent through publication and validation.

## Connect or contribute

[Connect an agent](https://ruagentic.org/docs/PROTOCOLS.md) through MCP, conditional WebMCP, or the hosted A2A and Agent Auth services. The [platform](https://ruagentic.org/docs/PLATFORM.md) provides private scan/audit reports and synthetic HTTP recovery checks. Reports expire after 30 days. Your business actions remain on your service.

Use the [HTTP quick start](https://ruagentic.org/docs/QUICKSTART.md) and [compatibility runner](https://ruagentic.org/docs/COMPATIBILITY.md) when implementing action recovery. Existing action profiles remain at 1.0.0; preserve the original contracts and clients for unfinished requests. Tools 1.3.0 support Site Profile 1.1.0 without changing action or receipt semantics. Contributions are welcome through [GitHub](https://github.com/sam1siam/agentic).


---

Source: https://ruagentic.org/docs/GOVERNANCE.md

# Governance
Agentic is an open project maintained by sam1siam. Specification changes, compatibility decisions, and release notes are published in the repository.

Original project code, schemas, and documentation are available under Apache-2.0. Third-party components retain their licenses. Participation does not require a paid account or permission from a central registry.

Submit changes through a GitHub issue describing the problem, current alternatives, intended client behavior, compatibility impact, and a reproducible example. Substantive changes need a pull request with normative text, schema changes where necessary, and behavioral tests. Keep decisions and dissent public.

The founding maintainer reviews changes. Invite additional maintainers after sustained substantive contributions; document appointments publicly. Once there are at least three maintainers, specification changes should require two approvals, including one from a maintainer outside the submitting organization when possible. Record conflicts of interest. Use issue discussion for disputes, then a written maintainer decision with rationale.

Agentic uses explicit semantic versions for its profile and tools. Preserve the requirements and artifacts of published versions. A breaking profile change requires a new major version and a migration guide; compatible additions and corrections require documented versioned releases. Each release must include validation and behavioral checks appropriate to its changes. Independent implementation reports strengthen compatibility evidence and remain distinct from project-authored checks.

Explore an existing community or neutral project home when outside implementers are engaged. AAIF Sandbox and relevant W3C Community Groups are potential routes, not current memberships or endorsements. Well-known URI registration, if pursued, is a separate step from format standardization.

Contributors agree to respectful, technical discussion. Harassment, threats, and disclosure of private credentials or personal data are not acceptable. Maintainers may remove such content and document moderation decisions without republishing harmful details.


---

Source: https://ruagentic.org/docs/INTEGRATIONS.md

# Integration guide

The initial Agentic binding supports one POST submission and two GET operations in an OpenAPI 3.1 document. It intentionally does not replace authentication, endpoint discovery, or an agent runtime's permission model.

For runnable MCP tools, WebMCP pages, and A2A / Agent Auth discovery configuration, see [Protocol setup and implementation status](https://ruagentic.org/docs/PROTOCOLS.md).

## Service checklist

1. Choose one record-creation operation in a sandbox.
2. Atomically persist the principal, action, idempotency key, exact input, and result. Reject the same key with different input.
3. Expose authoritative request lookup. Return `request_id`, `status`, and `resource_id` using the contract in SPEC.md section 4.
4. Expose a resource read that identifies the original request and required input evidence.
5. Describe the three operations with inline OpenAPI parameters. Bind their operation IDs in the profile.
6. Publish the profile on the service origin, and test the advertised retention window and failures.

An API that only offers idempotency, without a way to reconcile the request or identify its resulting resource, cannot satisfy this specification. Do not invent endpoints in a profile. A gateway can implement missing behavior only if it can make authoritative guarantees about the underlying operation; proxying HTTP alone is insufficient.

## Consumer integration

Keep the profile, OpenAPI snapshot, origin, input, and request ID in a durable record before sending. The project exposes `executeAction` in `lib/client.ts`, `httpTransport` in `lib/http-transport.ts`, and the single-host `SqliteLedger` in `reference/node/ledger.ts`.

The host authorizes the action before execution, approves the destination, chooses the credential context, and isolates ledgers by authenticated principal and environment. The reference CLI illustrates local execution; production authentication remains the host adapter's responsibility. A production adapter must apply those host policies rather than forwarding publisher-specified credentials.

Treat receipts as observations. Store them privately, preserve their timestamps, and surface `pending` or `unknown` to the host instead of mapping either to success or retry.

## Alongside other conventions

These are optional coexistence patterns. Agentic does not require agents.txt, agents.json, or llms.txt. Configure protocol clients with the direct endpoints in the connection guide.

| Existing convention | Coexistence approach |
| --- | --- |
| [llms.txt](https://llmstxt.org/) | Link to a Markdown integration guide. Offer page Markdown alternates and `describedby` links to the documentation index. |
| [agent.json / AWP](https://www.agent-json.org/) | Keep capability and authentication discovery there. Pass the Agentic profile URL explicitly to your adapter; no standardized Agentic binding is claimed. |
| OpenAPI | Keep operation schemas in OpenAPI; reference IDs instead of duplicating endpoints in Agentic. The 1.0 subset is intentionally limited. |
| Arazzo | Compare existing workflow verification and recovery with the profile. An Arazzo mapping is future work, not an implemented adapter. |
| MCP and other tool runtimes | Wrap an authorized host operation around the same execution contract. Tool descriptions or annotations alone do not establish the service's behavior. |

No reciprocal support, partnership, or endorsement from these projects is implied. These integration patterns do not establish cross-project interoperability.

## Evaluate your integration

Compare against the team's competent existing recovery workflow. Measure implementation effort, maintenance burden, duplicate resources, false success, and unresolved outcomes. If the shared file saves no meaningful work, report that result and consider contributing a narrower extension to an existing convention instead.


---

Source: https://ruagentic.org/docs/LAB.md

# Recovery lab

The [recovery lab](https://ruagentic.org/lab/) is an in-memory browser simulation. Select a scenario and run it to compare blind retry, idempotent retry, and Agentic verification. Inspect calls, duplicate resources, outcome, and trace; download the Agentic receipt for the selected run.

Scenarios include a lost response, unavailable status, stale resource read, mismatched evidence, pending work, an expired tracking window, and a fresh successful action. The scenario list in the interface is authoritative for its available controls.

The deterministic [comparison report](https://ruagentic.org/reports/benchmark.json) also includes a competent existing verification workflow. That workflow can achieve the same result. The benefit of a shared profile must be tested as reduced integration or maintenance effort, not assumed from the simulation.

For actual HTTP disconnection and persistent SQLite recovery, run the [quick start](https://ruagentic.org/docs/QUICKSTART.md). For an independently written consumer, use the [compatibility runner](https://ruagentic.org/docs/COMPATIBILITY.md). Browser simulation results are not production reliability estimates or independent adoption.


---

Source: https://ruagentic.org/docs/MIGRATION.md

# Migrate to Agentic 1.0

Agentic 1.0.0 uses explicit version identifiers for the action profile, receipt, schemas, and generated text index. The 1.0 validators accept the 1.0.0 contract only.

## New actions

1. Install and pin `ruagentic@1.3.0` and the matching service/client implementation.
2. Set the profile's `agentic` field to `1.0.0`. Use `agentic-1.0.schema.json` for profile validation and `receipt-1.0.schema.json` for receipt validation.
3. Generate new receipts with the `1.0.0` version identifier. Preserve historical receipts exactly as recorded; changing their version would not retest or reverify the original action.
4. Revalidate the profile against the service's actual OpenAPI document and run behavioral checks for request tracking, idempotency, status reconciliation, and resource evidence.
5. Regenerate `agentic.txt` from the validated profile. The current generator uses `Agentic-Text: 1.2` and its `Profile-Version` is `1.0.0`. Deploy the JSON and TXT together. Use `--legacy` only when retaining TXT 1.0 output; its existing bytes and JSON contract remain supported.

```sh
npm install -g ruagentic@1.3.0
agentic validate agentic.json openapi.json
agentic text agentic.json
agentic text agentic.json --check
```

The TXT generator refuses to overwrite an existing file. Review and replace a stale generated index deliberately before regenerating it. A version-field change alone does not establish behavioral compatibility.

## Unfinished requests

Preserve each unfinished request's original profile and OpenAPI snapshots, saved input, request ID, ledger, and installed compatible client. Do not relabel an in-flight request as 1.0.0, replace its saved contract, migrate it by changing its request ID, or repeat its write.

Reconcile the original attempt with the client and contract that created it. If that is unavailable or tracking has expired, keep the outcome unresolved and use the host's explicit reconciliation or handoff process. Upgrade new work separately after the new implementation passes its checks.

Retain original receipts and reports with their recorded versions and observation times. Generate fresh 1.0.0 results when verifying the upgraded integration; historical evidence is not automatically evidence for the new version.


---

Source: https://ruagentic.org/docs/OVERVIEW.md

# Agentic

The generator also supplies README.md and directory listing text. The TXT and Markdown outputs explain [Agentic](https://ruagentic.org), the specification and tools project, and [RUAGENTIC](https://ruagentic.com), the official Agentic directory for agentic AI MCP servers and tools. [Publish and check the complete set](https://ruagentic.org/docs/PUBLICATION.md).

**Make your website readable to agents.** Enter your URL to generate `agentic.json` and `agentic.txt` from public documentation, API descriptions, llms.txt, and advertised agent connections.

## Start with your website

1. [Generate](https://ruagentic.org/generate/): scan a public URL, review discovered sources, and download JSON, TXT, README, and listing text.
2. Publish the pair at `/agentic.json` and `/agentic.txt` on your domain.
3. [Audit](https://ruagentic.org/audit/): check the published JSON, linked documents, and matching text index.

The JSON is the structured source of truth. The TXT file is a readable index generated from it. No central registry is required.

## Two profile types

[Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md) describes documentation, OpenAPI operations, and advertised MCP, A2A, or Agent Auth links. It can be generated from public sources. A linked endpoint is not a verified service or an authorization grant. The scanner reads a bounded selection of public sources; it does not execute API actions or MCP tools.

[Action Profile 1.0](https://ruagentic.org/docs/SPEC.md) describes how a supporting client submits an action once, checks the original request, and verifies its result after a lost response. Its service must implement durable request tracking and the stated evidence checks. Existing valid action profiles are preserved during generation; missing recovery behavior is never inferred.

## Tools and documentation

Tools 1.3.0 support Site Profile 1.1.0, Action Profile 1.0.0, and their generated TXT indexes. Code and specifications are Apache-2.0. [Install the CLI](https://ruagentic.org/docs/GETTING-STARTED.md), [compare formats](https://ruagentic.org/docs/COMPARE.md), or [connect an agent](https://ruagentic.org/docs/PROTOCOLS.md).

The [hosted platform](https://ruagentic.org/docs/PLATFORM.md) also provides synthetic recovery checks and private reports. Our root Agentic files describe that ticket service. The reference consumers and tests are project-authored; no independent adoption or standards endorsement is claimed.


---

Source: https://ruagentic.org/docs/PLATFORM.md

# Hosted testing platform

## Website discovery

`POST /api/platform/discover` accepts `{ "url": "https://your-site.com" }` for an owner authenticated by the browser session or platform credentials. The generator creates its browser session automatically. Reports use kind `discovery`, remain private, and expire after 30 days. Limits are three scans per minute per owner and six per minute per client IP, including hosted MCP discovery calls. [Scanner limits](https://ruagentic.org/docs/SITE-PROFILE.md#discovery-and-auditing) bound network reads and file generation. No database migration is required beyond the existing report store.

The [Agentic platform](https://ruagentic.org/platform/) runs synthetic recovery tests over HTTP with a PostgreSQL service and request ledger. This is separate from the browser lab simulation and the loopback Python reference service.

The [production verification record](https://ruagentic.org/reports/platform-live.json) records the live checks performed by the project. It is project-authored evidence for the tested deployment.

## Recovery sandbox

Start a test to create an isolated private session. Choose normal completion, response failure after commit, interruption after submission, status outage, mismatched evidence, or pending status. Only the fixed synthetic ticket input is used by the console.

The response-failure scenario returns HTTP 503 after the resource commit. It does not claim to reproduce a physical network disconnect. The interruption scenario stops client execution after submission. Resume starts a fresh HTTP invocation and reconstructs the client from the persisted PostgreSQL ledger, with no repeat submission. The local compatibility runner additionally tests actual process termination.

Each report includes observed HTTP responses, a recovery trace, the receipt, committed-write count, resource count, and status reads. A structure pass, project-authored test, or synthetic result is not independent certification.

The service profile is at https://ruagentic.org/api/platform/service/agentic.json and its OpenAPI document at https://ruagentic.org/api/platform/service/openapi.json. Service operations require the session bearer token or authenticated internal execution. Request IDs are scoped to the principal. The tracking window is 24 hours; retained tombstones prevent reuse of an old request ID from creating another resource.

## Public URL auditor

The [auditor](https://ruagentic.org/audit/) accepts a website or full JSON URL and reads its profile, same-origin OpenAPI bindings, matching TXT index, and optional llms.txt documentation index. See [audit checks and report semantics](https://ruagentic.org/docs/AUDIT.md). It reports content types, sizes, and status codes. It makes no action submissions and does not prove runtime idempotency, authorization, retention, or recovery behavior.

Only public HTTPS on port 443 is accepted. All resolved IP addresses must be public. Connections pin the resolved address while retaining TLS hostname verification. Redirects, compressed responses, private networks, credentials in URLs, oversized bodies, and long requests are rejected. The profile limit is 64 KiB; OpenAPI is 256 KiB per document, up to five documents.

## Reports and sessions

Private reports and A2A tasks are isolated by session or authenticated agent. The console shows up to 100 recent reports. Reports expire after 30 days. A daily cleanup removes expired reports, tasks and temporary cache entries. An explicit sharing action creates an unguessable report link; disabling sharing immediately invalidates it.

Session credentials are random, stored as hashes, and delivered in an HttpOnly, SameSite cookie. Exporting a bearer token rotates the browser's credential. Revoking the session invalidates that token and private-history access. This anonymous sandbox does not offer customer account recovery or cross-device login. Do not submit secrets or personal information in audit URLs or uploaded profiles.

## Agent connections

See [Connect an agent](https://ruagentic.org/connect/): public MCP, conditional WebMCP page tools, A2A 1.0 JSON-RPC testing tasks, and autonomous Agent Auth registration, grants, execution and revocation.

## Operations

The static website and Node 24 Vercel Function share one deployment. A free Neon PostgreSQL database stores requests, ledgers, reports, tasks, rate limits and Agent Auth state. Direct database connections are required for PostgreSQL session advisory locks. Neon transaction-pooled URLs must not be used for those locks.

Required environment variables: `DATABASE_URL_UNPOOLED` (or direct `DATABASE_URL`), `BETTER_AUTH_SECRET`, `CRON_SECRET`, and `AGENTIC_ORIGIN=https://ruagentic.org`. Keep them in the hosting environment. Run `node scripts/platform-migrate.ts` before deployment with those variables available. Never run migrations on each HTTP request.

Public requests are rate limited in PostgreSQL; testing, auditing and registration have additional limits. Logs contain route, method, response status and duration, not bearer credentials, bodies or query strings. Daily cleanup uses a secret-protected Vercel cron endpoint. Requests and ledger tombstones outlive the 24-hour tracking window to prevent duplicate writes.

For local development, use an isolated PostgreSQL database, set `.env.platform-test`, run migrations and `npm run platform:dev`, then `npm run dev`. The frontend development proxy connects to the loopback platform server on port 3002. `AGENTIC_ALLOW_LOCAL=1` is for local tests only.


---

Source: https://ruagentic.org/docs/PRIOR-ART.md

# Prior work and positioning
Research checked September 7, 2026. These projects cover different parts of the agent ecosystem; inclusion is not an adoption or endorsement claim.

- [llms.txt](https://llmstxt.org/): concise website context and links.
- [AGENTS.md](https://agents.md/): instructions for coding agents in repositories.
- [Wildcard agents.json](https://github.com/wild-card-ai/agents-json): API contracts and flows built on OpenAPI.
- [OpenAPI Arazzo](https://spec.openapis.org/arazzo/latest.html): workflows, outputs, success criteria, and failure actions. Agentic should reuse its machinery where useful.
- [Agentic Resource Discovery](https://github.com/ards-project/ard-spec): discovery and federated search for agent resources.
- [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html): API catalogs.
- [A2A](https://a2a-protocol.org/): agent descriptions, communication, tasks, and artifacts.
- [MCP tool annotations](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/): behavioral hints; metadata is not enforcement.
- [WebMCP specification](https://webmachinelearning.github.io/webmcp/): structured tools in web applications.
- [Agent Permissions](https://github.com/las-wg/agent-permissions.json): advisory interaction permissions.
- [Verified Tool Calls Improve LLM Agent Reliability Under Non-Atomic Failures](https://arxiv.org/abs/2608.02645): direct research precedent for postcondition verification and interrupted-call recovery.

Agentic does not claim invention of idempotency, status reconciliation, receipts, or verification. Agentic provides a focused shared profile and reproducible behavioral tests for interrupted action recovery. Its integration guide explains how it works alongside existing API descriptions and agent protocols.


---

Source: https://ruagentic.org/docs/PROTOCOLS.md

# MCP, WebMCP, A2A, and Agent Auth

Tools 1.3.0 generation results include agentic.json, TXT 1.2, README.md and LISTING.md. Hosted `audit_agentic_url` accepts optional `readmeUrl` and returns publication status plus remedies without changing JSON/API `valid` semantics. [Publication specification](https://ruagentic.org/docs/PUBLICATION.md).

Tools 1.3.0 expose `discover_agentic_site` to local and hosted MCP and the generator's conditional WebMCP tools. It accepts `{ "url": "https://your-site.com" }` and returns JSON, TXT, README, and listing text with a discovery report. It reads public documents and records advertised protocol URLs without invoking discovered tools. [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md) can list these links; the 1.0 action schema remains unchanged.

Agentic 1.0 describes action tracking and recovery through OpenAPI. Discovery, tool transport, agent messaging, and authorization keep their own protocols. Adding a declaration does not implement a protocol.

## Current implementation

| Protocol   | Available                                                                                                          | Not implemented                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| MCP        | Public Streamable HTTP at `/mcp`, plus local stdio. Specification, generation, validation and hosted URL auditing. | Hosted mutation tools.                                         |
| WebMCP     | Generator, validator, and recovery lab register page tools when the browser exposes the supported API.             | Support in every browser or every agent host.                  |
| A2A        | Hosted A2A 1.0 JSON-RPC testing agent, PostgreSQL tasks and report artifacts.                                      | Streaming, push notifications and cancellation after dispatch. |
| Agent Auth | Official provider: registration, signatures, autonomous grants, execution, replay protection and revocation.       | Human account delegation and payments.                         |

Use the [connection guide](https://ruagentic.org/connect/) for client examples and the [platform](https://ruagentic.org/platform/) for live verification. Hosted services use one PostgreSQL-backed testing engine. See [platform operations and retention](https://ruagentic.org/docs/PLATFORM.md).

## Public endpoints

- MCP: `https://ruagentic.org/mcp`. Five read-only tools; no token required. The additional hosted tool is `audit_agentic_url` with `{ "url": "https://your-service.example/agentic.json" }`.
- A2A card: `https://ruagentic.org/.well-known/agent-card.json`; endpoint: `https://ruagentic.org/a2a`. Create a private session token in the platform. Send `Authorization: Bearer <token>` and `A2A-Version: 1.0`. `SendMessage` accepts a data part with `{ "kind": "recovery", "scenario": "response-lost" }` or `{ "kind": "audit", "url": "...", "readmeUrl": "https://raw.example/README.md" }` (readmeUrl is optional). Retrieve results with `GetTask` and the returned ID.
- Agent Auth: `https://ruagentic.org/.well-known/agent-configuration`. Configure the official `@auth/agent` client with `urls: ['https://ruagentic.org']` for direct discovery. Autonomous capabilities are `agentic.validate` and `agentic.sandbox.run`.

Agent Auth uses inline public keys, one-hour grants, a one-day maximum agent lifetime, persistent replay detection, and revocation checks. Remote JWKS URLs are not supported. The verification flow registers an agent, executes validation, revokes it and tests rejection of an unused signed token. It does not create a human account.

## Connect the local MCP server

Clone the repository and run `npm ci` with Node 24. Configure your MCP host with the absolute path to this checkout:

```json
{
  "mcpServers": {
    "agentic": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/agentic/reference/mcp/server.ts"]
    }
  }
}
```

On Windows, use a JSON-escaped absolute path such as `C:\\projects\\agentic\\reference\\mcp\\server.ts`. The host must be able to find Node 24; use its full executable path if necessary. Host configuration formats vary; the example uses the common `mcpServers` convention. Do not use `npm run mcp` as the host command: npm writes a banner to stdout. For a terminal-only smoke check, `npm run --silent mcp` starts the same stdio server and waits for a client.

Tools:

- `discover_agentic_site`: takes a public website `url` and returns JSON, TXT, README, and listing text plus a source report.
- `get_agentic_spec`: returns the site and action specifications bundled with the checkout.
- `generate_agentic_profile`: takes `origin` and optional `actionId`, returns the ticket starter and validation result.
- `validate_agentic_profile`: takes JSON text in `profile` and optional `openapi`. Limits: 64 KiB and 256 KiB respectively.

The server uses the official MCP TypeScript SDK 2.0.0. Specification, manual generation, and validation tools work on bundled documents or supplied text. Discovery reads bounded public HTTPS sources. None executes the ticket action or writes local files. The host remains responsible for permissions and its own logging. No credentials are required for these local tools.

## Use WebMCP page tools

Open /generate/, /validate/, or /lab/ in a compatible browser. Each page registers its tool through `document.modelContext.registerTool` when available and unregisters on unmount using an abort signal. This follows the current WebMCP specification; earlier browser implementations may expose a different API. The regular page controls work without WebMCP.

Website discovery updates the visible generator and returns all four publication files with its report. The advanced action-template tool returns profile data without changing the page. Validation and lab tools update the visible result. The lab remains a browser simulation, not an HTTP execution test. Registration is conditional and is not a claim that a particular agent host can invoke these tools.

## Documentation and direct connections

Use the endpoint URLs above and the [connection guide](https://ruagentic.org/connect/) to configure a client. A2A publishes its own AgentCard, and Agent Auth publishes its own provider discovery document. Neither requires a separate agents.txt or agents.json manifest on this site.

The generated /agentic.txt index links to the live synthetic service profile at /agentic.json. It is a reading aid, not a protocol or authorization manifest. The optional /llms.txt index links to Agentic documentation and connection instructions. In the [generator](https://ruagentic.org/generate/), expand **Optional: create an llms.txt documentation index** to create an llms.txt starter for your service. Edit its /docs/, /agentic.txt, and /agentic.json links to match your published files. The generator makes no network calls.

Action Profile 1.0 remains a separate action contract; its schema rejects added protocol fields. Site Profile 1.1 uses its versioned resources array for descriptive protocol links. Pass the profile URL explicitly or link it from documentation.

## Implement A2A and Agent Auth

For another service, deploy an A2A implementation using the official SDK and publish an AgentCard matching its exact protocol version, bindings, skills, and security requirements. Test message and task interactions before advertising the card. ruagentic.org's testing agent uses the official JavaScript SDK and persists caller-scoped tasks and artifacts.

For Agent Auth, implement the server flow and persistent identity/grant storage described by the upstream protocol. Validate signatures, audience, expiry, permissions, approval, and revocation before protecting any action with it. Scope the Agentic ledger by the authenticated principal and environment. Renewing credentials must not create a new logical request or trigger a repeat write. A revoked agent must not bypass authorization through a status or resource read.

The hosted sandbox provides the concrete service for autonomous authorization testing. It isolates agents by identity and limits grants to validation and synthetic recovery tests. A customer-facing human delegation integration would require that customer's account and approval model.

## Primary references

- [MCP server guide](https://modelcontextprotocol.io/docs/develop/build-server)
- [WebMCP specification](https://webmachinelearning.github.io/webmcp/)
- [A2A specification](https://a2a-protocol.org/latest/specification/)
- [Agent Auth discovery](https://agent-auth-protocol.com/docs/discovery)
- [Agent Auth server implementation](https://agent-auth-protocol.com/docs/server)

References reviewed on 2026-09-07. These projects have not endorsed Agentic or confirmed compatibility.


---

Source: https://ruagentic.org/docs/PUBLICATION.md

# Publish Agentic files and a README

Tools 1.3.0 generate four files from a website or a validated profile:

| File | Purpose |
| --- | --- |
| `agentic.json` | The authoritative Site Profile 1.1.0 or Action Profile 1.0.0. |
| `agentic.txt` | TXT 1.2: a readable index and clearly labeled Agentic project references. |
| `README.md` | Service description, published file links, public documentation, project references, and maintenance instructions. |
| `LISTING.md` | A reusable title, short/full description, website, documentation, and advertised connection links for directory submissions. |

The generator provides individual copy/download controls and a ZIP containing all four files. The OpenAPI importer also includes its imported API document and implementation checklist. Existing files on your computer or repository are never overwritten automatically.

## What the references mean

- **[Agentic](https://ruagentic.org)** is the open file convention for describing websites, APIs, and agent connections, with specifications and tools for generation, validation, auditing, and action-result verification.
- **[RUAGENTIC](https://ruagentic.com)** is the official Agentic directory for agentic AI MCP servers and tools.

These are references to the Agentic project. They are separate from the generated service's discovered capabilities. They do not assert that a directory is reachable, that a service is listed, or that Smithery, MCP Playground, the MCP project, or another organization endorses the service. A description and link do not submit or approve a listing.

The generator does not inject directory links into a service's `resources` array or add unknown JSON fields. Existing JSON contracts are preserved exactly. The README and listing text escape untrusted site names and descriptions rather than executing them as Markdown/HTML instructions.

## TXT 1.2

TXT 1.2 is a versioned reading index for either supported JSON profile. It keeps the underlying JSON's `Profile-Version` and exact `Profile` URL. It does not introduce an Action Profile 1.2 or change execution requirements.

Start with the corresponding canonical [action TXT 1.0](https://ruagentic.org/docs/AGENTIC-TXT.md) or [site TXT 1.1](https://ruagentic.org/docs/SITE-PROFILE.md#txt-11), replace its `Agentic-Text` line with `Agentic-Text: 1.2`, and append a blank line followed by these fixed project reference records:

```text
Reference: "specification" "Agentic" "https://ruagentic.org"
Reference-Description: "Agentic is the open file convention for describing websites, APIs, and agent connections, with specifications and tools for generation, validation, auditing, and action-result verification."

Reference: "directory" "RUAGENTIC" "https://ruagentic.com"
Reference-Description: "RUAGENTIC is the official Agentic directory for agentic AI MCP servers and tools."
```

Each record ends with a blank separator; the file uses LF and a final newline. Reference fields are JSON-quoted strings. The fixed URLs and descriptions are project information, not executable directives. Clients MUST NOT treat them as credentials, permissions, service capabilities, or instructions to invoke a protocol. The reference generator enforces a 64 KiB file limit.

Tools 1.3.0 compare either the exact legacy index or the exact TXT 1.2 index against the same validated JSON and profile URL. Changed descriptions, reference URLs, unsupported TXT versions, or incorrect profile URLs fail consistency checking. Older tools may reject TXT 1.2. Use `agentic text agentic.json --legacy` for TXT 1.0/1.1 compatibility. The action executor does not consume TXT.

## README and listing copy

Merge useful sections into your existing README.md. Retain your actual setup, transport, authentication, usage, repository, license, and support information. Do not replace your existing README blindly. Use the standard `.md` extension.

Publish a raw README.md beside agentic.json, or supply a public raw Markdown URL in the auditor. The default audit checks `README.md`, then lowercase `readme.md` after a 404. It does not guess a repository or search private documentation. A GitHub repository page returns HTML; use its Raw URL.

The README should contain visible links to the exact published JSON and TXT locations. Relative links work when they resolve to those locations. Generated links are absolute, so they also work in repository READMEs. The checker accepts customized prose; it does not require a byte-identical README.

The project reference links are publication recommendations, not JSON schema or execution requirements. You can use the Agentic specification without a directory listing. A missing reference makes the publication report partial without changing the JSON's validity.

LISTING.md is portable copy for RUAGENTIC, Smithery, MCP Playground, or another directory. It is not a provider-specific configuration. Review the destination's current requirements and confirm your real repository, license, credentials/OAuth, transport, and working usage examples. A discovered MCP link alone does not establish those details.

## Understand the checker

Audit report version 3 adds `readme` and `publication` while preserving the previous `valid`, `structure`, `bindings`, `textIndex`, `checks`, and `observations` fields. `textIndex.version` reports the observed TXT version when available.

| Publication result | Meaning | Next step |
| --- | --- | --- |
| `successful` | JSON/API checks passed, TXT matches, and README/file/reference link checks passed. | Keep files current and rerun after changes. |
| `partial` | JSON/API checks passed, but a companion file, reference, content type, or remaining document check needs attention. | Follow each reported remedy, then rerun. |
| `failed` | JSON/API validation failed, TXT conflicts with JSON, or README links point to different Agentic files. | Correct the failing files or restore their public access, then rerun. |

`valid` continues to describe JSON and API/document checks only. README and TXT publication issues do not change that field. Use `publication.status === "successful"` when requiring the complete publication. Informational notes about deliberately untested MCP connections do not prevent a successful file audit.

The checker retrieves companion availability even when JSON is missing or invalid. It checks README presence, raw content, JSON/TXT link destinations, and links to both project domains. It never follows README links, invokes advertised protocols, verifies every sentence, certifies a service, or confirms listing acceptance. References inside fenced code, inline code, or HTML comments do not satisfy README link checks.

README reads use public-only HTTPS/DNS/IP checks, no redirects, no credentials, a 64 KiB limit, and bounded timeouts. An explicitly supplied README URL may be on another public domain; this establishes neither ownership nor affiliation. Private files can be reviewed locally instead.

## CLI and agent tools

```sh
npm install -g ruagentic@1.3.0
agentic discover https://your-site.com --out agentic-files
agentic bundle agentic.json --out publication-files
agentic text agentic.json --check
agentic audit https://your-site.com --publication
agentic audit https://your-site.com --readme https://raw.example/repo/README.md --publication
```

`discover` scans the website; `bundle` generates the four files from existing validated JSON without fetching a website. Both create a new directory and refuse to overwrite an existing one. Use `--profile-url` with `bundle` or `text` for a nested/custom JSON location.

The default CLI audit exit code retains JSON/API semantics. `--publication` exits nonzero for partial or failed publication. MCP `discover_agentic_site` and `generate_agentic_profile` return all four files. Hosted MCP `audit_agentic_url` accepts optional `readmeUrl` and returns the version 3 report. Browser controls use the same output and checker.


---

Source: https://ruagentic.org/docs/QUICKSTART.md

# Quick start

Run Agentic 1.0 with synthetic tickets on a loopback reference service. The service intentionally supports fault injection for recovery testing and has no authentication; keep it local.

## Requirements

- Node 24.x and npm.
- Python 3.11 or later, available as `python`.
- Two terminals in the repository directory.

```sh
git clone https://github.com/sam1siam/agentic.git
cd agentic
npm ci
python -m pip install -r reference/python/requirements.txt
```

## Run an interrupted action

First terminal:

```sh
python reference/service/server.py --fault response-lost
```

Second terminal:

```sh
npm run client -- http://127.0.0.1:4318 example-001 "Example ticket"
```

The service commits one ticket, then closes the connection before delivering its first response. The client reconciles the request, reads the ticket, verifies its identity and subject, and prints a JSON receipt with `outcome: succeeded`.

Repeat the exact client command. It returns the saved receipt without creating another ticket. Its `observed_at` is the original observation time. Stop the service with Ctrl+C. State lives under the ignored `.agentic-state` directory.

The Python client can run the same operation:

```sh
python reference/python/client.py http://127.0.0.1:4318 python-example-001 "Python example ticket"
```

## Create a profile for your service

```sh
npm run init -- --origin https://your-service.example --out agentic.json
npm run validate -- agentic.json examples/tickets/openapi.json
```

The initializer refuses to overwrite existing files. Its starting operations and evidence are for the ticket example. Replace them with your actual service contract, then validate against your actual OpenAPI file. Validation does not call the service.

The [browser generator](https://ruagentic.org/generate/) offers the same starting contract with editable fields and a JSON download. The [validator](https://ruagentic.org/validate/) accepts pasted profile and OpenAPI JSON.

Publish the file on the service origin as `/agentic.json` with `Content-Type: application/json`, or give the profile URL explicitly to a supporting client. The service needs real atomic request tracking, idempotency, status lookup, and correlated resource evidence. Uploading JSON alone does not implement those capabilities.

## Verify the implementation

```sh
npm test
npm run typecheck
npm run conformance -- --adapter integrations/node-reference.json --out .agentic-state/compatibility-report.json
```

The first command exercises the project tests. The compatibility runner can also drive your own client; see [COMPATIBILITY.md](https://ruagentic.org/docs/COMPATIBILITY.md). Project-authored runs are reference checks, not independent adoption.

## Troubleshooting

- **Port 4318 is busy:** use `--port 4319` on the server and the matching client origin.
- **Request ID reused with changed input:** restore the original input to reconcile that attempt. Only choose a new ID when intentionally authorizing a separate new action.
- **Outcome unknown or pending:** retain the request ID and ledger. Inspect the reason; do not automatically repeat the mutation.
- **Python is unavailable:** install Python 3.11+ and ensure the `python` command works before the HTTP tests.
- **Schema passes but binding fails:** the binding requires inline OpenAPI 3.1 operations without server overrides or parameter references. See [INTEGRATIONS.md](https://ruagentic.org/docs/INTEGRATIONS.md).
- **Expired tracking:** use the host's reconciliation or human handoff process. Expiry is not proof the action failed.

See the [normative specification](https://ruagentic.org/docs/SPEC.md) and [security limits](https://ruagentic.org/docs/SECURITY.md) before integrating another service.


---

Source: https://ruagentic.org/docs/README.md

# Agentic documentation

- [Publish files and a README](https://ruagentic.org/docs/PUBLICATION.md): TXT 1.2 project references, automatic README/listing copy, and successful/partial/failed audit results with fixes.

Start by [generating files from a website](https://ruagentic.org/docs/GENERATOR.md). [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md) defines public resources, documented API indexes, and TXT 1.1. [Action Profile 1.0](https://ruagentic.org/docs/SPEC.md) defines optional request recovery and result verification. Tools 1.3.0 support both types.

> Guides for Site Profile 1.1, Action Profile 1.0, and publication tools 1.3.

## Start here

- [Generate](https://ruagentic.org/docs/GENERATOR.md): Create and download agentic.txt and agentic.json together.
- [Audit](https://ruagentic.org/docs/AUDIT.md): Check public files, API links, and TXT consistency.
- [Compare](https://ruagentic.org/docs/COMPARE.md): How Agentic fits with other agent formats.
- [About](https://ruagentic.org/docs/ABOUT.md): Purpose, maintainers, and contribution paths.

- [Get started](https://ruagentic.org/docs/GETTING-STARTED.md): Generate files, install tools, and connect an agent.

- [Quick start](https://ruagentic.org/docs/QUICKSTART.md): Installation, synthetic ticket action, recovery, and troubleshooting.
- [Generator](https://ruagentic.org/docs/GENERATOR.md): Browser and local profile creation.
- [Hosted platform](https://ruagentic.org/docs/PLATFORM.md): HTTP recovery tests, public URL audits, private history, sharing and operations.
- [Examples](https://ruagentic.org/docs/EXAMPLES.md): Complete profile, OpenAPI contract, and illustrative receipt.
- [FAQ](https://ruagentic.org/docs/FAQ.md): Support, service requirements, safety boundaries, and versioning.

## Implement and test

- [Normative specification](https://ruagentic.org/docs/SPEC.md): JSON protocol requirements.
- [agentic.txt companion](https://ruagentic.org/docs/AGENTIC-TXT.md): Generated action index, publication, and consistency checks.
- [Migrate to 1.0](https://ruagentic.org/docs/MIGRATION.md): New version identifiers, revalidation, and preservation of unfinished requests.
- [Integration guide](https://ruagentic.org/docs/INTEGRATIONS.md): Client, service, and adjacent-convention integration.
- [Protocol setup](https://ruagentic.org/docs/PROTOCOLS.md): Public MCP, WebMCP tools, A2A testing tasks, and autonomous Agent Auth.
- [Validator](https://ruagentic.org/docs/VALIDATOR.md): Structure and binding checks.
- [Recovery lab](https://ruagentic.org/docs/LAB.md): Browser scenarios and their limitations.
- [Compatibility runner](https://ruagentic.org/docs/COMPATIBILITY.md): Run independently written client code.
- [Conformance](https://ruagentic.org/docs/CONFORMANCE.md): Evidence levels and test limits.
- [Security](https://ruagentic.org/docs/SECURITY.md): Operational controls and remaining gaps.

## Contribute

- [Governance](https://ruagentic.org/docs/GOVERNANCE.md): Change process and version compatibility.
- [Roadmap](https://ruagentic.org/docs/ROADMAP.md): Product development priorities.
- [Changelog](https://ruagentic.org/docs/CHANGELOG.md): Published changes.
- [Prior art](https://ruagentic.org/docs/PRIOR-ART.md): Related approaches.
- [Route inventory](https://ruagentic.org/docs/SITE-MAP.md): What this site actually serves.
- [Brand assets](https://ruagentic.org/docs/BRAND.md): Logo files and visual identity.

## Example commands

```sh
git clone https://github.com/sam1siam/agentic.git
cd agentic
npm ci
python -m pip install -r reference/python/requirements.txt
python reference/service/server.py --fault response-lost
```

In a second terminal, run `npm run client -- http://127.0.0.1:4318 example-001 "Example ticket"`. Repeating the exact command returns the saved receipt. See the quick start for requirements and troubleshooting.


---

Source: https://ruagentic.org/docs/ROADMAP.md

# Product roadmap

Agentic 1.0.0 is available for direct use. Work follows concrete bugs, integration needs, and contributions.

| Area | Available now | Next work when needed |
| --- | --- | --- |
| Files | Versioned specification, schemas, OpenAPI and documentation generators | Resolve focused specification issues through versioned changes |
| Tools | Validator, CLI release, GitHub Action, and agent skill | Improve setup and distribution based on installation feedback |
| Hosted services | Recovery sandbox, URL auditor, report history, MCP, A2A, and Agent Auth | Maintain availability, dependencies, and operational controls |
| Integrations | Node and Python reference clients, local service, compatibility runner | Accept optional implementation reports and focused adapters |
| Governance | Open source, public issues, documented change process | Maintain published compatibility requirements and document future version changes |

Use the files, tools, and hosted services directly. Report results with the tested implementation and version; contributions and implementation reports are optional.


---

Source: https://ruagentic.org/docs/SECURITY.md

# Security and operational limits

Agentic profiles describe action behavior. Authorization remains the responsibility of the host and service, including when they use the hosted Agent Auth integration.

Report vulnerabilities through the repository's private security reporting feature if available. Do not publish credentials, private receipts, or exploitable details in an issue. For non-sensitive bugs, include a minimal reproduction and affected version.

The public manifest is untrusted data. Keep authorization in the host; restrict destinations independently of manifest validation. Do not forward credentials to newly discovered origins or redirects. Bind request ledgers to the current principal and environment. Set response limits and timeouts.

The local reference service binds to 127.0.0.1 and has no authentication. Its fault injection and inspection endpoints are intentionally for tests. Do not expose it directly to the Internet.

SQLite ledgers store inputs and receipts. Protect their directory, keep them out of Git, and define a retention policy. The included locks work only among processes on a single machine; PID reuse fails closed. They are not distributed leases.

No static declaration or receipt establishes service honesty or prevents prompt injection. JSON Schema validation is one parsing check, not authorization or a trust decision.

A machine-readable contact record is published at `https://ruagentic.org/.well-known/security.txt` (RFC 9116); it points at the repository's private security reporting form and expires in September 2027, so move its `Expires` line forward before then.


---

Source: https://ruagentic.org/docs/SITE-MAP.md

# Published routes and capabilities

`/README.md` serves this project's public README. Generation now includes README.md and LISTING.md; the audit accepts an optional raw README URL and provides publication status and remedies. See [Publication](https://ruagentic.org/docs/PUBLICATION.md).

The primary `/generate/` flow scans a website and produces JSON, TXT, README, and listing text through `POST /api/platform/discover`. [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md) and `/schemas/site-1.1.schema.json` describe the output. Manual action configuration remains under Advanced.

This inventory distinguishes browser tools, hosted services and the separate local reference API.

| Route                            | What is available                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| /                                | Project overview and complete starting profile                                                          |
| /audit/                          | Public website or JSON URL checks with readable results and report download                             |
| /compare/                        | Comparison with documentation, repository, capability, API, and tool formats                            |
| /about/                          | Purpose, maintainers, requirements, and contribution paths                                              |
| /spec/                           | Human reading guide to the normative specification                                                      |
| /generate/                       | Action profile, OpenAPI import and optional llms.txt generators, copy/download, conditional WebMCP tool |
| /examples/                       | Profile, OpenAPI, and synthetic receipt examples                                                        |
| /validate/                       | Local structure and optional OpenAPI binding validation                                                 |
| /lab/                            | In-memory recovery comparison; no production API calls                                                  |
| /docs/                           | Guide index, quick start, FAQ, and reference links                                                      |
| /adopt/                          | Getting started, CLI installation, GitHub Action, and integration guides                                |
| /platform/                       | Hosted recovery tests, URL auditor, Agent Auth verification and private/shared reports                  |
| /connect/                        | Public MCP, WebMCP, A2A and Agent Auth client setup                                                     |
| /mcp                             | Read-only Streamable HTTP MCP tools                                                                     |
| /a2a                             | Authenticated A2A 1.0 JSON-RPC testing tasks                                                            |
| /.well-known/agent-card.json     | A2A card matching the hosted agent                                                                      |
| /.well-known/agent-configuration | Live autonomous Agent Auth provider discovery                                                           |
| /api/platform/*                  | Isolated sandbox, auditing, sessions and evidence reports                                               |
| /api/auth/*                      | Official Agent Auth registration, grants, execution and revocation                                      |
| /agentic.txt                     | Generated action index for the hosted synthetic ticket service                                          |
| /agentic.json                    | Authoritative JSON profile of that service                                                              |
| /llms.txt                        | Concise Markdown documentation index                                                                    |
| /llms-full.txt                   | Optional combined documentation bundle                                                                  |
| /docs/*.md                       | Plain Markdown source documents                                                                         |
| /schemas/*.json                  | Versioned profile and receipt schemas                                                                   |
| /examples/tickets/*              | Static illustrative example files                                                                       |
| /brand/*.svg                     | Downloadable identity assets                                                                            |
| /sitemap.xml                     | Human page inventory                                                                                    |
| /robots.txt                      | Public crawl guidance                                                                                   |

Every human route has an `index.md` alternative. HTML metadata exposes `rel="alternate"` with `type="text/markdown"`; the deployment's Link header also identifies the relevant alternate and `/llms.txt` as `describedby`.

The hosted runtime uses PostgreSQL and Node 24 Vercel Functions; see [platform operations](https://ruagentic.org/docs/PLATFORM.md). It provides synthetic testing, not customer actions or payments. The separate local Python reference server serves `/agentic.txt`, `/agentic.json`, `/openapi.json`, `/tickets`, `/requests/{requestId}`, and `/tickets/{ticketId}` on loopback only. Optional WebMCP tools remain conditional on browser support.


---

Source: https://ruagentic.org/docs/SITE-PROFILE.md

# Agentic Site Profile 1.1

For TXT 1.2 with project descriptions, automatically generated README.md/LISTING.md, and publication checks, see [the publication specification](https://ruagentic.org/docs/PUBLICATION.md). Tools 1.3.0 preserve this JSON schema and continue accepting its original TXT 1.1 index.

Version: 1.1.0. Released: 2026-09-07. License: Apache-2.0.

A site profile describes a website's public documentation, APIs, and advertised agent connections. A publisher can generate it from public sources without defining an executable action contract. Serve the JSON at `/agentic.json` and its generated text index at `/agentic.txt`.

This is an additive profile type. Action Profile 1.0.0 and receipt 1.0.0 retain their published requirements. A site profile is not an action profile and MUST NOT be passed to the action executor. A supporting client uses the linked API or protocol's own contract and authorization rules.

## Required JSON fields

The [site schema](https://ruagentic.org/schemas/site-1.1.schema.json) defines exact fields and limits. Unknown fields are rejected.

| Field | Meaning |
| --- | --- |
| `agentic` | Exactly `1.1.0`. |
| `type` | Exactly `site`; distinguishes descriptive site information from action execution contracts. |
| `origin` | Canonical HTTPS origin of the website. |
| `name` | Site name, up to 160 characters. |
| `description` | Public site description, up to 600 characters. |
| `resources` | One to forty resource records. At least one must identify a retrieved source. |
| `apis` | Zero to five OpenAPI indexes, each with up to 160 operations. |

The optional `$schema` is `https://ruagentic.org/schemas/site-1.1.schema.json`. Tools MUST pin the supported schema locally and MUST NOT fetch a publisher-supplied schema URI.

## Resource records

Each resource requires `kind`, `url`, `source`, and `availability`. An optional `title` is at most 160 characters.

- `kind`: `website`, `documentation`, `llms`, `openapi`, `mcp`, `a2a`, `agent-auth`, or `agentic`.
- `url`: the resource's HTTPS URL.
- `source`: the public document from which the URL was discovered. A directly retrieved well-known file may name itself as the source.
- `availability`: `retrieved` when the document was successfully read, or `linked` when a retrieved source referenced it.

URLs are at most 2048 characters and MUST NOT contain credentials, queries, fragments, or alternate ports. Explicit local/private IP addresses and localhost links are rejected. A `(kind, url)` pair MUST be unique.

An external connection can be listed as `linked`. That does not establish ownership, protocol conformance, authorization, or permission to forward credentials. `retrieved` records the publisher's observation of a document, not an independent attestation. Consumers MUST independently enforce their network and authorization policies.

## OpenAPI indexes

Each API has `document`, `openapi`, and `operations`. `document` MUST reference a `retrieved` OpenAPI resource in the same profile. The index copies facts from that document:

- `method`: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or TRACE.
- `path`: the documented API path, up to 512 characters. It starts with one `/` and contains no query, fragment, or backslash.
- Optional `operationId`: copied verbatim when present, up to 160 characters. Missing identifiers MUST NOT be invented.
- Optional `summary`: public operation summary, up to 240 characters.

Method/path pairs MUST be unique within an API. The full OpenAPI document remains authoritative, including server URLs, security requirements, parameters, and response schemas. Indexed operations are descriptions, not executable Agentic actions.

No retention window, idempotency guarantee, request/result correlation, success state, or recovery rule may be inferred merely from operation names or marketing descriptions. Those require the separately defined [Action Profile 1.0](https://ruagentic.org/docs/SPEC.md) and a conforming implementation.

## TXT 1.1

Generate the text index from validated JSON. JSON remains authoritative. Site TXT uses:

```text
# Agentic site index
# Generated from JSON. Resources are discovery information, not execution instructions.
Agentic-Text: 1.1
Profile: https://service.example/agentic.json
Profile-Version: 1.1.0
Type: site
Origin: https://service.example
Name: "Example service"
Description: "Public API and documentation."

Resource: "documentation" "https://service.example/docs"
Availability: retrieved
Source: "https://service.example/docs"
```

Resources follow JSON array order; optional titles use `Title: <quoted string>`. API sections use `OpenAPI: <quoted document URL>`, `OpenAPI-Version: <quoted version>`, and one `Operation: <quoted method> <quoted path> [<quoted operation ID>]` per indexed operation. Empty lines separate records. Strings use JSON quoting with control, directional, and invisible formatting characters escaped by the published generator. TXT does not reconstruct an executable contract.

The `Profile:` URL MUST share the profile origin and contain no credentials, query, or fragment. Serve both files as UTF-8; use `application/json` and `text/plain; charset=utf-8`. Keep each generated file within 64 KiB. Action TXT 1.0 remains byte-compatible and unchanged.

## Discovery and auditing

The website generator reads public HTML, text/Markdown, JSON metadata, and OpenAPI 3 JSON documents. It follows same-origin links selected as documentation or API descriptions and checks conventional Agentic, OpenAPI, llms.txt, A2A, and Agent Auth metadata paths. It records advertised MCP URLs without invoking tools. It does not run browser JavaScript or access login-protected documents.

The scan permits up to three redirects per document, only on the same HTTPS origin or its exact www/non-www counterpart. Every hop is checked against public-only DNS/IP rules. Redirect bodies are closed immediately. Cross-origin documentation and connection links are recorded without being fetched.

Limits: twenty-two HTTP attempts, five concurrent documents, one MiB per response, eight MiB of response-body allowance, with failed reads charged their full allowance, and a forty-second scan deadline, with a bounded DNS lookup finishing at most five seconds later. Sources or operation indexes may be shortened to keep the file size bounded; the report explains truncation. The report records failures and the observation time.

If a valid existing action profile is found, the generator preserves it and regenerates its matching TXT. The root profile takes priority over nested profiles, unless the user explicitly supplied another profile URL. Missing OpenAPI binding checks are reported, not invented.

The auditor validates site structure, the serving origin, matching TXT, and up to five retrieved same-origin documents, prioritizing OpenAPI operation indexes. Linked or external protocols are not invoked. Its `valid` field excludes optional TXT consistency, which remains in `textIndex` and `checks`; require `valid && textIndex.status === "matched"` when enforcing a matching pair.

## Tools and compatibility

Tools 1.3.0 support Site Profile 1.1.0 alongside Action Profile 1.0.0. Earlier tools must be upgraded to read the site profile. The 1.0 action executor intentionally rejects site profiles before any ledger or network access. Existing action contracts, receipts, and in-flight request identities must not be relabeled.

```sh
npm install -g ruagentic@1.3.0
agentic discover https://your-site.example --out agentic-files
agentic validate agentic-files/agentic.json
agentic text agentic-files/agentic.json --check
```

The `discover` command creates a new directory containing agentic.json, agentic.txt, README.md, LISTING.md, and a discovery report; it refuses to overwrite an existing directory. The `discover_agentic_site` tool exposes the same scanner through local and hosted MCP. The generator page also exposes it through WebMCP when the browser supports that API.


---

Source: https://ruagentic.org/docs/SPEC.md

# Agentic Action Profile 1.0

For automatically generated website resources and API indexes, see [Site Profile 1.1](https://ruagentic.org/docs/SITE-PROFILE.md). This document continues to define Action Profile 1.0 only; its published execution requirements are unchanged.
Version: 1.0.0. Released: 2026-09-07.
Maintainer: [sam1siam](https://github.com/sam1siam). License: Apache-2.0.
This document defines the Agentic JSON action profile. The optional [agentic.txt companion](https://ruagentic.org/docs/AGENTIC-TXT.md) is a separate generated reading aid and does not change this profile schema or its execution requirements.

## 1. Purpose and boundaries
Agentic describes how a participating client tracks an action, reconciles an uncertain submission, and verifies its outcome. The initial binding supports a small OpenAPI 3.1 subset: one POST submission, one GET request-status operation, and one GET resource-verification operation.

This is not a discovery protocol, an authorization protocol, or an exactly-once delivery guarantee. The service must implement its advertised behavior. Clients must apply their existing authorization, credential, network, and user-interaction policies.

The keywords MUST, MUST NOT, SHOULD, and MAY describe requirements of this specification.

## 2. Publication and processing
A publisher MAY serve the UTF-8 JSON profile at /agentic.json using application/json, or provide an explicit profile URL. Automatic filename discovery is not assumed. No Agentic well-known URI is registered by this project.

The profile MUST validate against schemas/agentic-1.0.schema.json and pass the semantic binding checks below. Version 1.0.0 is the only supported version. Unknown fields are rejected in this version to expose typos; future extensions require a new schema version. Duplicate JSON member names are invalid publisher output. The reference JSON parsers do not detect duplicate member names; strict duplicate-key detection is a known implementation gap.

The profile SHOULD be at most 64 KiB. Reference tools enforce this limit when accepting pasted profile text. Referenced OpenAPI documents SHOULD be at most 256 KiB. Clients MUST pin the supported schema locally and MUST NOT fetch arbitrary schemas named by a publisher's $schema value.

Origin MUST be a canonical HTTPS origin without credentials, path, query, or fragment. Explicit local development MAY use HTTP on localhost, 127.0.0.1, or [::1]. Production hosts MUST independently enforce approved destinations; HTTPS alone does not establish that a destination is trusted or public.

A profile MUST NOT grant itself authority over other origins. The reference binding accepts only root-relative paths without traversal segments, escapes, query strings, fragments, backslashes, or network-path references. A client MUST reject redirects during action execution. Cross-origin endpoints and OpenAPI server overrides are unsupported in 1.0.

Publishers SHOULD use normal HTTP cache controls and ETags. A running request MUST remain bound to its saved profile and OpenAPI snapshot. If either changes, the reference clients reject reuse of that request ID. Migration requires an explicit host reconciliation process.

## 3. Profile fields
The versioned JSON Schema is authoritative for field types, limits, and required fields. All fields in each action below are required.

| Field | Meaning |
| --- | --- |
| agentic | Exact supported version: 1.0.0 |
| origin | Authoritative service origin |
| actions | One to 32 action descriptions with unique IDs |
| actions[].id | Stable action identifier |
| description | Short description, treated as untrusted data |
| openapi | Root-relative URL of the OpenAPI 3.1 description |
| submit | Operation ID of the POST mutation |
| status | Operation ID of the GET request-status operation |
| verify | Operation ID of the GET resource read |
| request.header | Idempotency-Key in this binding |
| request.scope | principal-action: keys are scoped to the authenticated principal and action |
| request.retentionSeconds | Minimum advertised tracking and deduplication window, 60 to 604800 seconds |
| bindings.statusRequestId | Required path parameter receiving the saved request ID |
| bindings.verifyResourceId | Required path parameter receiving the authoritative resource ID |
| evidence.resourceIdPointer | JSON Pointer to the resource's own ID |
| evidence.requestIdPointer | JSON Pointer linking the resource to the original request |
| evidence.statePointer | JSON Pointer to its observable state |
| evidence.successValues | Resource states that count as successful completion |
| evidence.inputBindings | Input/resource pointer pairs whose values must match |
| recovery.maxChecks | One to ten status-check attempts per execution |
| recovery.checkDelayMs | Delay between check attempts, zero to 5000 milliseconds |
| recovery.timeoutMs | Per-request timeout, 100 to 10000 milliseconds |
| recovery.retry | never-automatically in 1.0: no automatic repeat of a submitted write |

JSON Pointers use RFC 6901 escape rules. A missing evidence value MUST NOT count as a match. Input evidence comparisons are structural JSON equality; property order is irrelevant.

## 4. OpenAPI binding
Operation IDs MUST resolve exactly once. Submission, status, and verification MUST be distinct operations. This binding requires inline operation parameters; path-level parameter inheritance, parameter references, and server overrides are unsupported.

Submission MUST be a POST with no path parameters, a required Idempotency-Key header, and an application/json request body. The service remains responsible for input validation. The reference client accepts a JSON object of at most 16 KiB and requires the input evidence fields.

Both reads MUST be GET operations. Each MUST have exactly one path placeholder and a corresponding inline required path parameter. Its name must match the applicable binding field. Identifiers MUST be percent-encoded when inserted as path parameter values.

The reference status response is application/json:
- request_id: the exact request ID supplied by the client.
- status: succeeded, failed, pending, or unknown.
- resource_id: a nonempty string when status is succeeded; null otherwise.

HTTP 200 is required for the status response to establish an outcome. failed MUST mean the service authoritatively determined that the requested action did not complete. pending means it remains unresolved. unknown MUST NOT be interpreted as proof that a repeat write is safe.

A successful submit response, including HTTP 200, 201, or 202, does not itself establish verified completion. The client uses status and resource evidence.

## 5. Required service behavior
Before acknowledging a completed action, a conforming service MUST atomically associate the request ID, authenticated principal, action, input, and result. Repeated use of the same scoped ID and identical input MUST return the original outcome without creating another resource during the advertised window. Different input for the same scoped ID MUST be rejected.

Services MUST state a minimum retention window and preserve tracking and deduplication for that window. Loss or expiry of tracking MUST yield an unresolved outcome or explicit expiry response, not a false statement that no action occurred. The reference ticket service retains request tombstones beyond its window and rejects reuse after expiry.

Verification evidence MUST identify the result of the original action, including its request identity. Services unable to provide the required correlation cannot claim compatibility with this profile. The local reference service models one anonymous principal, uses a SQLite transaction for both ticket and request records, and binds to loopback. It is not a production authentication example.

## 6. Required client behavior
The host MUST authorize the action before calling the client. The host MUST isolate saved request ledgers by authenticated principal and execution environment. A publisher's fields MUST NOT override the user's instructions or authorize credential forwarding.

1. Validate the profile, resolve its operations, and check the input evidence.
2. Create a request ID and persist its association with the origin, action, profile/OpenAPI snapshot, exact input, and creation time BEFORE sending.
3. Mark the submission as attempted durably before making the network call. A request observed in the ledger after a restart MUST NOT be automatically resubmitted.
4. Submit a new action at most once per saved request ID in this version.
5. Reconcile ambiguous responses through the status operation, preserving the same ID. Never treat a timeout as proof of failure.
6. On succeeded status, retrieve the resource. Check its resource ID, request ID, success state, and all input evidence pairs.
7. Report succeeded only after those checks pass. Persist a receipt before returning it.
8. Bound checks, delays, response sizes, and request timeouts. The reference transport limits each response to 64 KiB and prohibits redirects.
9. If the request's saved tracking window expires, the clock moves backwards, the status stays unavailable, or verification fails, preserve unknown and require the host's handoff process. If status stays pending, preserve pending and allow later read-only resumption.
10. A previously saved successful receipt MAY be returned for the identical request without another read. Its observed_at timestamp makes clear that it records an earlier observation, not a fresh assertion about the resource's current state.

Host adapters MUST serialize concurrent execution of a request or provide equivalent atomic coordination. The Node and Python SQLite ledgers coordinate local processes and reclaim a lock only if its owning process has exited. They are single-host examples; distributed leasing and account-aware storage are outside their scope.

Design note (non-normative). The request ID is minted by the client and persisted before the nondeterministic model or tool step runs, and it is forwarded unchanged as the service's Idempotency-Key. It is deliberately not derived from the tool arguments: an agent that retries after re-entering the model can produce different arguments for the same intended action, and two intentionally distinct actions can share identical arguments, so an arguments-derived key both drifts and collides. Deduplication therefore happens on the service side (section 5), while the client-side ledger only replays a recorded outcome or fails closed on an in-flight request; it never guesses whether a lost response completed. This is the same split as a payment processor's idempotency key: framework-side result caching alone cannot prevent a duplicate side effect whose first acknowledgement was lost.

## 7. Receipts
Receipts MUST validate against schemas/receipt-1.0.schema.json. They include the version, request ID, action ID, origin, outcome, observation time, resource ID or null, and a reason.

A succeeded receipt MUST additionally contain evidence: resource URL, resource/request IDs, observed state, and the input/resource pointer pairs checked. The receipt is an observation record, not a signature or proof that a service is honest.

Receipts and saved inputs can be sensitive. They MUST NOT be published in a public manifest. Storage access, retention, and deletion belong to the host. The reference examples keep SQLite files in the ignored .agentic-state directory.

## 8. Conformance and evolution
Structural validity, binding validity, behavioral test results, and independent adoption are separate claims. See CONFORMANCE.md for the test matrix and limitations. Passing tests establishes behavior only for the versions and scenarios tested.

The project provides Node and Python reference consumers from the same authorship. Compatibility reports identify the implementation, tested version, scenarios, and evidence. Independent adoption requires a separately authored implementation; it is not implied by a release version.

Future work includes Arazzo profile mapping, richer retry contracts, a staged commit binding, and another protocol binding when implementation feedback justifies it. These are not supported features of 1.0.


---

Source: https://ruagentic.org/docs/VALIDATOR.md

# Profile validator

The [browser validator](https://ruagentic.org/validate/) checks pasted `agentic.json` against the pinned Site Profile 1.1 or Action Profile 1.0 schema and semantic rules. An optional pasted OpenAPI document enables action operation-binding checks. Site profiles check resource provenance and operation-index structure locally; use the public audit for live document checks. It does not fetch external schemas, inspect live services, or execute actions.

Use the profile and OpenAPI tabs, load the ticket example or paste your own files, and select **Validate profile**. Editing either file clears the old result. Profile input is limited to 64 KiB and OpenAPI input to 256 KiB. The copy action copies the profile JSON.

Checks cover field types and limits, canonical HTTPS origin, unique action IDs, same-origin paths, distinct operations, required idempotency headers, supported JSON submissions, and required read-path parameters. Duplicate JSON member detection remains a known parser gap documented in SPEC.md.

The command-line equivalent is:

```sh
npm run validate -- profile.json openapi.json
```

A valid profile is a declaration, not evidence that a service implements its claims. Use the compatibility runner and service review to test behavior. See [CONFORMANCE.md](https://ruagentic.org/docs/CONFORMANCE.md).