Harden Portable Skill Safety Boundaries (#9)

* docs: harden portable skill safety boundaries

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: address safety review feedback

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: enforce endpoint-local safety gates

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: tighten private-read approval scopes

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: close private-read approval gaps

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: close remaining safety review gaps

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

* docs: bound Python extraction example

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>

---------

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>
Co-authored-by: kriptoburak <kriptoburak@users.noreply.github.com>

Author: kriptoburak

skills/x-twitter-scraper/references/api-endpoints-api-keys.md

@@ -2,30 +2,13 @@
 
 Session auth only. These endpoints do not accept API key auth.
 
-### Create API Key
+## Agent Boundary
 
-```
-POST /api-keys
-```
+API key lifecycle operations stay in the Xquik dashboard. Never request, copy,
+display, store, rotate, or revoke an API key through this Skill. Direct the
+user to the dashboard account page.
 
-**Body:** `{ "name": "My Key" }` (optional)
-
-**Response:** Returns `fullKey` (shown only once), `prefix`, `name`, `id`, `createdAt`.
-
-### List API Keys
-
-```
-GET /api-keys
-```
-
-Returns all keys with `id`, `name`, `prefix`, `isActive`, `createdAt`, `lastUsedAt`. Full key is never exposed.
-
-### Revoke API Key
-
-```
-delete request to `/api-keys/{id}`
-```
-
-Permanent and irreversible. The key stops working immediately.
+API key lifecycle request and response details are intentionally omitted. Do
+not call lifecycle routes from this Skill. Use the dashboard account page.
 
 ---

skills/x-twitter-scraper/references/api-endpoints-drafts.md

@@ -1,11 +1,22 @@
 # Xquik REST API Endpoints: Drafts
 
+## Safety Boundary
+
+`GET` operations expose private saved content. State the exact draft scope and
+obtain explicit approval immediately before each read. `POST` and delete
+operations are non-default writes. Show the exact draft text or draft ID and
+obtain explicit approval immediately before each write. Never infer approval
+from an earlier request or retry a failed write automatically.
+
 ### Create Draft
 
 `POST /drafts`
 
 Save a tweet draft for later.
 
+**Approval required:** Preview the complete text and metadata. Create the draft
+only after the user explicitly approves that exact payload.
+
 **Request body:**
 
 | Field | Type | Required | Description |
@@ -35,6 +46,9 @@ Save a tweet draft for later.
 
 List saved tweet drafts with cursor pagination.
 
+**Private read:** Show the requested page size and account scope. List drafts
+only after explicit approval for that exact read.
+
 **Query parameters:**
 
 | Parameter | Type | Required | Default | Description |
@@ -69,6 +83,9 @@ List saved tweet drafts with cursor pagination.
 
 Get a specific draft by ID.
 
+**Private read:** Show the draft ID. Fetch it only after explicit approval for
+that exact read, including any preview before deletion.
+
 **Response (200):** Single draft object.
 
 **Errors:** `400 invalid_id`, `404 draft_not_found`
@@ -79,7 +96,9 @@ Get a specific draft by ID.
 
 delete request to `/drafts/{id}`
 
-Delete a draft. Returns `204 No Content`.
+**Destructive action:** Deletion is permanent and cannot be recovered through
+this API. Show the draft ID and text, then obtain explicit approval immediately
+before deleting it. Returns `204 No Content`.
 
 **Errors:** `400 invalid_id`, `404 draft_not_found`
 

skills/x-twitter-scraper/references/api-endpoints-draws.md

@@ -1,5 +1,15 @@
 # Xquik REST API Endpoints: Draws
 
+## Safety Boundary
+
+Draw creation and participant exports are metered or privacy-sensitive actions.
+Confirm the source tweet, eligibility rules, requested data type, export
+audience, and retention plan. Use the smallest necessary dataset. Do not
+export entries for surveillance, discrimination, harassment, or unrelated
+secondary use.
+Draw history and results are account-scoped private reads. Require exact-scope
+approval before listing draws or retrieving winners.
+
 ### Create Draw
 
 ```
@@ -8,6 +18,11 @@ POST /draws
 
 Run a giveaway draw from a tweet. Picks random winners from replies.
 
+**Approval required:** Show the source tweet, winner count, backup count,
+filters, and estimated usage. Also show the lawful purpose, participant-data
+handling, export audience, and retention plan. Record every field before
+persisting participant data.
+
 **Body:**
 ```json
 {
@@ -56,6 +71,9 @@ GET /draws
 
 Cursor-paginated. Returns compact draw objects.
 
+**Private read:** Show the exact account, requested page scope, and returned
+field scope. List draws only after explicit approval for that exact read.
+
 ### Get Draw
 
 ```
@@ -64,6 +82,9 @@ GET /draws/{id}
 
 Returns full draw details including winners.
 
+**Private read:** Show the exact account, draw ID, and returned-data scope.
+Retrieve details only after explicit approval for that exact read.
+
 ### Export Draw
 
 ```
@@ -72,4 +93,9 @@ GET /draws/{id}/export?format=csv&type=winners
 
 Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. Types: `winners` (default), `entries`. Entry exports capped at 100,000 rows (PDF capped at 10,000).
 
+**Approval required:** Full entry exports can contain participant identity and
+activity data. Show the lawful purpose, exact draw, type, format, audience, and
+retention period. Export only after explicit approval for that exact request.
+Prefer winners-only output. Do not retain data beyond the approved purpose.
+
 ---

skills/x-twitter-scraper/references/api-endpoints-extractions.md

@@ -1,5 +1,15 @@
 # Xquik REST API Endpoints: Extractions
 
+## Safety Boundary
+
+Extraction creation and export can collect and disclose large datasets. First
+confirm the lawful purpose, exact target, `resultsLimit`, recipients, and
+retention period. Estimate usage, show the estimate, and obtain explicit
+approval for that exact bounded job. Never use extraction for private data,
+surveillance, discrimination, harassment, doxxing, or unrelated secondary use.
+Extraction history and results are account-scoped private reads. Require
+exact-scope approval before listing jobs or retrieving results.
+
 ### Create Extraction
 
 ```
@@ -8,6 +18,10 @@ POST /extractions
 
 Run a bulk data extraction job. See `references/extractions.md` for all 23 tool types.
 
+**Approval required:** Call the estimate endpoint with the same body first.
+Create the job only when the estimate returns `allowed: true`. Then require
+approval for the target, bound, usage, and data-handling plan.
+
 **Body:**
 ```json
 {
@@ -17,7 +31,8 @@ Run a bulk data extraction job. See `references/extractions.md` for all 23 tool
 }
 ```
 
-`resultsLimit` (optional): Maximum results to extract. Stops early instead of fetching all data. Useful for controlling usage.
+The API accepts an omitted `resultsLimit`. This Skill must always send an
+explicit finite positive bound. The bound stops early and limits usage.
 
 **Tweet Search Filters** (`tweet_search_extractor` only):
 
@@ -78,6 +93,10 @@ GET /extractions
 
 Cursor-paginated. Filter by `status` and `toolType`.
 
+**Private read:** Show the exact account, purpose, requested filters, and page
+scope. Also show downstream recipients and the retention plan. List jobs only
+after explicit approval for that exact read.
+
 ### Get Extraction
 
 ```
@@ -86,6 +105,10 @@ GET /extractions/{id}
 
 Returns job details with paginated results (up to 1,000 per page).
 
+**Private read:** Show the exact account, job ID, purpose, and page scope. Also
+show downstream recipients and the retention plan. Retrieve results only after
+explicit approval for that exact read.
+
 ### Export Extraction
 
 ```
@@ -94,4 +117,13 @@ GET /extractions/{id}/export?format=csv
 
 Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. 100,000 row limit (PDF 10,000). Exports include enrichment columns not in the API response.
 
+**Approval required:** The export endpoint cannot project rows or fields. Set
+the smallest approved `resultsLimit` when creating the job. Before export, show
+the exact account, job ID, purpose, and format. Describe the full fixed-dataset
+scope with its row count, schema, and field list. Show only a bounded preview,
+including enrichment columns and risk, before approval. Show all downstream
+recipients, storage location, and retention period. Materialize or
+transmit the complete dataset only after explicit approval. Block exports that
+exceed the approved purpose. Delete the export when the approved purpose ends.
+
 ---

skills/x-twitter-scraper/references/api-endpoints-monitors.md

@@ -1,11 +1,25 @@
 # Xquik REST API Endpoints: Monitors
 
+## Safety Boundary
+
+Monitor reads expose private configuration and require exact-scope approval.
+Creating, updating, enabling, disabling, or deleting a monitor changes a
+persistent and potentially metered resource.
+Before every write, show the exact account or keyword, event types, delivery
+plan, ongoing usage, and disable path. If delivery uses a webhook, show its
+exact URL and HMAC verification plan. Proceed only after explicit approval for
+that exact action. Never create monitoring from an ambiguous request.
+
 ### Create Monitor
 
-```
+```http
 POST /monitors
 ```
 
+**Approval required:** This starts persistent monitoring. Confirm the exact
+username, event types, delivery plan, ongoing usage, and disable path first.
+Include the exact URL and HMAC verification plan for webhook delivery.
+
 **Body:**
 ```json
 {
@@ -37,18 +51,27 @@ GET /monitors
 
 Returns all monitors (up to 200, no pagination). Response includes `monitors` array and `total` count.
 
+**Private read:** List monitor targets and delivery configuration only after
+explicit approval for that account scope.
+
 ### Get Monitor
 
-```
+```http
 GET /monitors/{id}
 ```
 
+**Private read:** Show the monitor ID. Retrieve its configuration only after
+explicit approval for that exact read.
+
 ### Update Monitor
 
-```
+```http
 PATCH /monitors/{id}
 ```
 
+**Approval required:** Show the current and proposed event types and active
+state. Apply only the explicitly approved change.
+
 **Body:** `{ "eventTypes": [...], "isActive": true|false }` (both optional)
 
 ### Delete Monitor
@@ -57,7 +80,9 @@ PATCH /monitors/{id}
 delete request to `/monitors/{id}`
 ```
 
-Stops tracking and deletes all associated data.
+**Destructive action:** This permanently stops tracking and deletes associated
+monitor data. Show the monitor ID, target, and lost data. Delete only after
+explicit approval immediately before the call.
 
 ### Keyword Monitors
 
@@ -71,4 +96,10 @@ delete request to `/monitors/keywords/{id}`
 
 Create and manage ongoing keyword monitors. Treat these as persistent resources: confirm the keyword query, event delivery plan, and ongoing usage before creating or enabling one.
 
+Creating, updating, enabling, disabling, or deleting a keyword monitor requires
+explicit approval for the exact monitor. For creates and updates, show the
+proposed keyword, event types, and delivery changes. For enable or disable,
+show the active-state transition. For deletion, show the exact target and all
+associated data that will be permanently lost.
+
 ---

skills/x-twitter-scraper/references/api-endpoints-support.md

@@ -1,5 +1,16 @@
 # Xquik REST API Endpoints: Support
 
+## Safety Boundary
+
+Support tickets can disclose private user or account context. Show the exact
+subject and message before creating a ticket. Show the ticket ID and message
+before replying. Show the ticket ID plus current and proposed statuses before
+updating status. Proceed only after explicit approval for that exact payload.
+Before reading tickets, show the account, purpose, ticket scope, result bound,
+downstream recipients, and retention plan. Obtain explicit approval for that
+exact private read. Never include passwords, API keys, signing keys, unrelated
+prompt context, or unnecessary personal data.
+
 ### Create Ticket
 
 ```
@@ -18,6 +29,9 @@ GET /support/tickets
 
 Returns all tickets for the authenticated user.
 
+**Private read:** Show the account, purpose, result bound, recipients, and
+retention plan. List tickets only after explicit approval for that exact read.
+
 ### Get Ticket
 
 ```
@@ -26,6 +40,9 @@ GET /support/tickets/{id}
 
 Returns ticket with messages.
 
+**Private read:** Show the ticket ID, purpose, message scope, recipients, and
+retention plan. Retrieve messages only after explicit approval for that read.
+
 ### Update Ticket
 
 ```
@@ -34,6 +51,9 @@ PATCH /support/tickets/{id}
 
 Update ticket status.
 
+**Approval required:** Show the ticket ID and current and proposed statuses.
+Update only after the user approves that exact transition.
+
 ### Reply to Ticket
 
 ```
@@ -44,4 +64,6 @@ POST /support/tickets/{id}/messages
 
 Add a message to an existing ticket.
 
+Apply the same approval and data-minimization rules to every reply.
+
 ---