From 5133bc20eb491f5ffd2f756737568d826aa437a6 Mon Sep 17 00:00:00 2001
From: s0lray <s0lray@users.noreply.github.com>
Date: Mon, 30 Mar 2026 17:41:51 -0400
Subject: [PATCH] Update README legend and contribution guide for enriched
 schema (THE-212)

The legend now documents the full set of tool metadata fields (description,
status, pricing, opsec, etc.) that have been added across 900+ tools. The
contribution guide shows the enriched JSON format as the recommended standard.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index d1c058c..4606bcd 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,33 @@ Please visit the framework at the link below and good hunting!
 https://osintframework.com
 
 ### Legend
-(T) - Indicates a link to a tool that must be installed and run locally  
-(D) - Google Dork, for more information: <a href="https://en.wikipedia.org/wiki/Google_hacking">Google Hacking</a>  
-(R) - Requires registration  
-(M) - Indicates a URL that contains the search term and the URL itself must be edited manually  
+
+#### Name Markers
+(T) - Indicates a link to a tool that must be installed and run locally
+(D) - Google Dork, for more information: <a href="https://en.wikipedia.org/wiki/Google_hacking">Google Hacking</a>
+(R) - Requires registration
+(M) - Indicates a URL that contains the search term and the URL itself must be edited manually
+
+#### Tool Metadata Fields
+Each tool entry in `arf.json` can include structured metadata beyond the name and URL:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | What the tool does |
+| `status` | string | `live`, `degraded`, `down`, or `deprecated` |
+| `pricing` | string | `free`, `freemium`, or `paid` |
+| `bestFor` | string | Primary use case in one line |
+| `input` | string | What the tool takes as input |
+| `output` | string | What the tool returns |
+| `opsec` | string | `passive` or `active` |
+| `opsecNote` | string | Operational security considerations |
+| `localInstall` | boolean | Corresponds to `(T)` marker |
+| `googleDork` | boolean | Corresponds to `(D)` marker |
+| `registration` | boolean | Corresponds to `(R)` marker |
+| `editUrl` | boolean | Corresponds to `(M)` marker |
+| `api` | boolean | Whether the tool offers an API |
+| `invitationOnly` | boolean | Whether access requires an invitation |
+| `deprecated` | boolean | Whether the tool is deprecated |
 
 ### For Update Notifications
 Follow me on Twitter: @jnordine - https://twitter.com/jnordine  
@@ -26,23 +49,37 @@ Feedback or new tool suggestions are extremely welcome!  Please feel free to sub
 
 ### Contribute with a GitHub Pull Request
 For new resources, please ensure that the site is available for public and free use.
-<ol start="1">
-  <li>Update the arf.json file in the format shown below. If this isn't the first entry for a folder, add a comma to the last closing brace of the previous entry.</li>
-</ol>
 
-```
+1. Update `arf.json` with your new tool entry in the appropriate category folder. Use the enriched format below:
+
+```json
 {
-  "name": "Example Name",
+  "name": "Example Name (T)",
   "type": "url",
-  "url": "http://example.com"
+  "url": "https://example.com",
+  "description": "Brief description of what the tool does and its key capabilities.",
+  "status": "live",
+  "pricing": "free",
+  "bestFor": "Primary use case in one sentence",
+  "input": "What the tool accepts (e.g., Username, Domain, IP address)",
+  "output": "What the tool returns (e.g., Profile matches, DNS records)",
+  "opsec": "passive",
+  "opsecNote": "Any operational security considerations for using this tool.",
+  "localInstall": true,
+  "googleDork": false,
+  "registration": false,
+  "editUrl": false,
+  "api": false,
+  "invitationOnly": false,
+  "deprecated": false
 }
 ```
 
-<ol start="2">
-  <li>Submit pull request!</li>
-</ol>
+At a minimum, include `name`, `type`, and `url`. The metadata fields are strongly encouraged as they help users understand each tool at a glance.
 
-Thank you!
+Append `(T)`, `(D)`, `(R)`, or `(M)` to the name when applicable, and set the corresponding boolean field to `true`.
+
+2. Submit your pull request!
 
 ## OSINT Framework Website