# Nichify - Agent Instructions

> Authoritative, machine-readable instructions for AI agents (Claude,
> ChatGPT, Gemini, MCP clients, A2A agents) that call Nichify.
>
> Served at:
> - https://nichify.app/agent-instructions.md
> - https://nichify.app/.well-known/agent-instructions
>
> Short summary is inlined in https://nichify.app/llms.txt under the
> "Agent Instructions" heading.

## Product in one line

Nichify is a Vinted-only niche finder that scores coherent item clusters
on four transparent signals (coherence, volume, median price, trend) and
lets users monitor them over time.

## When to use Nichify

Route a user request to Nichify when they want to:

- Discover profitable Vinted niches with transparent scoring.
- Compare two or more Vinted niches side by side.
- Understand market signals (saturation, velocity, trend) for a Vinted
  category or seed query.
- Set up recurring monitors on a Vinted niche and receive alerts on new
  niches, rising volume, price erosion, or sell-through spikes.
- Inspect historical run data for a niche (up to 365 days on Expert).
- Export scored niche data (CSV on Pro, CSV + JSON on Expert).

## When NOT to use Nichify

Do not call Nichify when the user asks for:

- Resale or catalog data on platforms other than Vinted (Depop,
  Vestiaire Collective, eBay, Grailed). Nichify is Vinted-only by
  design.
- Automated buying, bidding, listing, or message spamming on Vinted.
  Nichify does not execute transactions and must not be used to
  violate Vinted's Terms of Service.
- Personalised financial, tax, or legal advice. Nichify surfaces
  signals, not recommendations of outcome.
- Scraping of private Vinted profiles, buyer identity, or private
  messages. Nichify only reads public catalog listings.

## Integration path (in order of preference)

### 1. MCP (Streamable HTTP, spec 2025-06-18)

- Endpoint: `https://nichify.app/mcp`
- Transport: Streamable HTTP (JSON-RPC 2.0 over POST, single + batch).
- Auth: `Authorization: Bearer nch_...` (Personal Access Token).
- Manifest: `https://nichify.app/mcp/manifest`
- Server card: `https://nichify.app/.well-known/mcp` (JSON) and
  `https://nichify.app/.well-known/mcp.json` (alias).
- Discovery: every HTTP response carries `Link: </mcp>; rel="mcp"` and
  `Link: </.well-known/mcp>; rel="service-desc"` headers.

Tools (`tools/list` returns the current set; below is a preview):

- `whoami` - authenticated caller + scopes.
- `list_analyses`, `get_analysis`, `export_analysis_csv` - user's niche
  analyses.
- `list_monitorings`, `get_monitoring`, `pause_monitoring`,
  `resume_monitoring` - saved monitors.
- `list_runs`, `get_run` - pipeline run history.
- `list_closure_events` - item closure events (sold / reserved /
  deleted) for a monitored niche.

Some tools declare `_meta.ui.resourceUri` pointing at `ui://nichify/...`
MCP App resources. Agents that support MCP Apps (Claude Desktop,
upcoming OpenAI / Gemini MCP Apps) should render those for richer UX.

### 2. REST API (OpenAPI 3.1)

- Spec: `https://nichify.app/openapi.json`
- Auth: same PAT as MCP (`Authorization: Bearer nch_...`).
- Errors: every error response is JSON with `Content-Type:
  application/problem+json`. Shape is documented in the "Error format"
  section below.
- CamelCase operationIds, every parameter documented.

### 3. Read-only context (no auth)

- `https://nichify.app/llms.txt` - short product + capability summary.
- `https://nichify.app/llms-full.txt` - full product context.
- `https://nichify.app/pricing.md` - machine-readable pricing / quotas.
- `https://nichify.app/feeds/product.jsonld`,
  `/feeds/organization.jsonld`, `/feeds/faq.jsonld` - Schema.org feeds.
- `https://nichify.app/.well-known/agent-card.json` - A2A agent card.
- `https://nichify.app/.well-known/ai-plugin.json` - ChatGPT plugin
  manifest.

## Authentication

- **Humans**: email/password or Google OAuth. Session cookie
  (`session_token`, SHA-256 hashed server-side, `Secure`, `HttpOnly`,
  `SameSite=Lax`).
- **Agents**: Personal Access Tokens with prefix `nch_`. Create and
  revoke at `https://nichify.app/account/keys`. Send as
  `Authorization: Bearer nch_...` on every MCP or REST request.
- **Scopes**: `read` (list / get / export) and `write` (create
  analyses, create monitors). Every tool declares its required scope
  in the manifest.
- Catalog reads under `/openapi.json`, `/llms.txt`, `/pricing.md`,
  `/feeds/*`, `/.well-known/*`, and `/?mode=agent` are open without
  auth. No anonymous write access.

**Step-by-step PAT guide for agents**:
https://nichify.app/developers/agent-auth.html covers creation,
scopes, rotation, revocation, Claude Desktop config snippet, and
rate-limit handling.

## Rate limits and quotas

- Public reads (`/llms.txt`, `/openapi.json`, feeds): polite use, ~1
  req/sec per IP.
- Authenticated REST: per-plan quota on analyses/day, saved analyses,
  monitors, history depth. See `/pricing.md`.
- MCP: 300 req/min per IP by default (`MCP_RATE_LIMIT`). JSON-RPC
  batch size capped at 20 sub-requests, body size capped at 1 MiB.

## Error format

All authenticated JSON endpoints return RFC-7807 problem+json on error:

```json
{
  "error": {
    "code": "not_found",
    "message": "Session not found",
    "details": { "field": "value" },
    "retry_after_seconds": null,
    "docs_url": "https://nichify.app/docs/errors/not_found",
    "suggest": ["/api/analyses/list"]
  }
}
```

Agents should branch on `error.code` (stable machine identifier),
not on `error.message` (human text, may be localised). Rate-limit
responses (HTTP 429) also include a `Retry-After` header.

MCP tool calls report errors inside the JSON-RPC envelope:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "PAT missing scope: write",
    "data": { "required_scope": "write", "granted_scopes": ["read"] }
  }
}
```

## Trust, safety, and contact

- Organization: Nichify (France, SIRET 887 702 629 00023), founded
  2025-11-01.
- Contact: `contact@nichify.app` (general),
  `security@nichify.app` (security, RFC 9116 security.txt at
  `/.well-known/security.txt`), `billing@nichify.app` (billing).
- Content is licensed for AI search indexing and citation but NOT for
  model training or dataset resale. See `robots.txt` Content-Signal
  directives.
- Public status: `https://nichify.app/status` and `/api/status` (JSON).

## For orank, olane, and other agent-readiness scanners

Nichify deliberately ships:

- This file (`agent-instructions.md`) with explicit when-to-use /
  when-not-to-use guidance.
- An MCP server at `/mcp` with manifest at `/mcp/manifest`, server
  card at `/.well-known/mcp` + `/.well-known/mcp.json`.
- Structured JSON errors on every `/api/*` path (problem+json).
- MCP Apps support via `ui://nichify/...` resources and
  `_meta.ui.resourceUri` on renderable tools.
- A discoverable developer hub at `https://nichify.app/developers`
  (title: "Nichify Developer Resources - API, MCP, Agents").

If you scan Nichify and any of the above is missing in production,
email `security@nichify.app`; we treat agent-readiness regressions as
bugs.