BlackOrder per gli agenti AI: un catalogo ufficiale leggibile dalle macchine

Sempre più persone che cercano software non navigano: chiedono. Un assistente legge il web al posto loro, confronta e risponde con un link. Quell'assistente fa fatica con un sito come il nostro. Deve indovinare cosa fa un'app da una pagina di presentazione, non sa se la versione scritta nella pagina è ancora quella corrente, e non distingue un download gratuito da uno a pagamento senza leggere tre paragrafi. Quando sbaglia, la persona dall'altra parte riceve una risposta sbagliata con il nostro nome sopra.

Il rimedio non è scrivere prosa migliore per le macchine. È pubblicare i fatti una volta sola, in una forma che una macchina legge senza indovinare, dallo stesso posto da cui li legge il sito.

BlackOrder pubblica ora un catalogo ufficiale leggibile dalle macchine per gli agenti AI. Il punto di ingresso è blackorder.io/.well-known/agent.json, un unico documento che dice chi è BlackOrder, elenca gli endpoint, documenta i parametri di ricerca con esempi e contiene l'intero catalogo: un record per applicazione, con nome, descrizione, categoria, versione, macOS minimo, architettura, prezzo e gratuità, firma e notarizzazione, cosa sa fare, cosa fa con i tuoi dati, e la pagina ufficiale da cui una persona la scarica; e un record per ogni articolo di questo blog, con l'indirizzo canonico in inglese e in italiano, tag e date, e le app a cui si riferisce. Gli stessi dati sono serviti anche come agent card su agent-card.json, come catalogo nudo su ai-catalog.json e come breve riassunto in testo su llms.txt.

Niente è mantenuto a mano. Gli articoli vengono dal database del blog, versioni e requisiti dai canali di aggiornamento firmati che le app stesse verificano, e i titoli dell'App Store dalle schede della home. Pubblichi un'app o un articolo e compare; cambi una versione e il record cambia; togli qualcosa e sparisce, entro un minuto.

C'è un endpoint di ricerca, /api/agent/search, con una domanda in testo libero e filtri per tipo, categoria, piattaforma, prezzo, lingua e tag, che restituisce risultati ordinati per rilevanza sempre con l'indirizzo canonico BlackOrder. Ci sono gli endpoint delle app, degli articoli, della singola app o del singolo articolo, e un controllo di compatibilità che dice se un'app gira su un dato Mac.

Ogni risposta dichiara la propria provenienza: editore BlackOrder, dominio canonico blackorder.io, fonte ufficiale, e la data dell'ultima modifica dei contenuti. L'API non distribuisce mai software. Un agente può trovare e consigliare un'app, ma il download avviene sulla pagina ufficiale, dove decide la persona. La scoperta funziona come già funziona il web: un tag link nel head della home e di ogni pagina del blog, un'intestazione Link su ogni risposta, la pagina per gli agenti collegata dal footer, robots.txt e la sitemap.

Qualche esempio dice più di una specifica. Chiedere alla ricerca un editor audio professionale gratuito per macOS restituisce PeakLab per primo, con la sua pagina su questo blog. Chiedere uno spazio di lavoro gratuito per agenti di coding su Mac restituisce Charlie. Chiedere tutte le app gratuite restituisce l'elenco vivo. Chiedere articoli su AI e coding restituisce quelli pertinenti. Ogni risposta include la pagina canonica da mostrare alla persona.

L'interfaccia è volutamente semplice: HTTPS e JSON, nessun SDK, nessun account, nessuna chiave, risposte memorizzabili per cinque minuti con ETag e Last-Modified, e uno schema versionato che potrà solo crescere. Le funzioni dietro gli endpoint hanno già la forma di strumenti, così un server MCP che esponga ricerca, dettagli dell'app, articolo, compatibilità, ultima versione e pagina ufficiale di download potrà seguire senza cambiare ciò che è pubblicato qui.

La documentazione per le persone, con l'elenco degli endpoint, i parametri e gli esempi di interrogazione, è su blackorder.io/agents.