feat(alexandria): document the 1-credit feedback refund

[nickscamara]

Summary

The API now refunds 1 credit for Alexandria session feedback (firecrawl/firecrawl#4980): the first feedback per website each UTC day, up to 10 credits per team per UTC day. This updates the CLI and skills, which said it gave no credit refund.

• firecrawl alexandria feedback --help describes the refund.
• Readable output for a same-day repeat now says the website was already refunded today, instead of "already submitted for this job". JSON output already passed creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached, alreadySubmitted, and warning through.
• Skills: firecrawl-alexandria gains the refund rules (one refund per website per day, the daily cap, stop when dailyCapReached), matching the search-feedback section. firecrawl-agent, firecrawl, and firecrawl-search mention the refund. README updated.
• Tests for the Alexandria refund output in both the refunded and already-refunded cases.

Merge after the API PR is deployed.

Made with Cursor

---

Summary by cubic

The Alexandria session feedback API now refunds 1 credit per submitted feedback, up to 10 credits per website and 100 credits per team each UTC day. Feedback must also be sent within about 2 minutes of the team's most recent Alexandria search, discovery, or execution; later submissions are rejected with FEEDBACK_WINDOW_EXPIRED.

• Updates help text, skills, and README to document the refund, the caps, and the 2-minute window instead of stating that feedback gives no credit.
• Readable output reports "Daily refund cap reached for this website" and passes websiteCapReached through to JSON output after either cap is hit.
• Adds CLI tests for refunded, already-refunded, and cap-reached output paths, and bumps the version to 1.26.1.

Merge after the API PR is deployed.

^{Written for commit 0a239c2. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 8 files

Confidence score: 3/5

• skills/firecrawl-alexandria/SKILL.md hides the response containing dailyCapReached, so callers may keep sending feedback after the team cap is reached. Make that response visible so callers can stop.
• In src/commands/feedback.ts, alreadySubmitted can be true even when the website’s first feedback arrived after the cap was exhausted, so saying it was refunded is inaccurate. Say the website was already submitted today instead.
• skills/firecrawl-agent/SKILL.md promises a refund even though refunds stop at the 10-credit team-per-UTC-day cap. Qualify the promise and tell agents to stop when dailyCapReached is true.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/firecrawl-agent/SKILL.md">

<violation number="1" location="skills/firecrawl-agent/SKILL.md:63">
P2: This states the refund as guaranteed, but Alexandria refunds stop at the 10-credit team-per-UTC-day cap. Qualify the promise and tell agents to stop when `dailyCapReached` is true, as the Alexandria skill already does.</violation>
</file>

<file name="skills/firecrawl-alexandria/SKILL.md">

<violation number="1" location="skills/firecrawl-alexandria/SKILL.md:36">
P2: The `--silent &` pattern below hides the response containing `dailyCapReached`, so callers cannot know when to stop sending feedback as instructed. Tell callers to inspect the response and avoid `--silent` or backgrounding when enforcing the cap.</violation>
</file>

<file name="src/commands/feedback.ts">

<violation number="1" location="src/commands/feedback.ts:368">
P2: `alreadySubmitted` can be true when the website’s first feedback arrived after the team cap was exhausted, so no credit was refunded. Say the website was already submitted today rather than claiming it was refunded.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Fix all with cubic | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This states the refund as guaranteed, but Alexandria refunds stop at the 10-credit team-per-UTC-day cap. Qualify the promise and tell agents to stop when dailyCapReached is true, as the Alexandria skill already does.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At skills/firecrawl-agent/SKILL.md, line 63:

<comment>This states the refund as guaranteed, but Alexandria refunds stop at the 10-credit team-per-UTC-day cap. Qualify the promise and tell agents to stop when `dailyCapReached` is true, as the Alexandria skill already does.</comment>

<file context>
@@ -60,4 +60,4 @@ firecrawl agent "<job-id>" --cancel
 ## Alexandria session feedback
 
-To report an Alexandria session outcome or a provider/capability gap, use `firecrawl alexandria feedback --rating good|partial|bad --url <website> --requested-functionality '<what was needed>' --objective '<the underlying goal of the task>' --rationale '<what happened>' --json`. Use observed results in the rationale. No job ID is needed; this session feedback has no job-age deadline and no credit refund. Optional `--provider-feedback` and `--capability-feedback` JSON arrays describe specific gaps; inspect `firecrawl alexandria feedback --help` for their fields. Use the capability issue `missing_capability` when a provider exists but lacks the needed capability, and `new_capability_request` (with `requestedFunctionality`) to ask for one.
+To report an Alexandria session outcome or a provider/capability gap, use `firecrawl alexandria feedback --rating good|partial|bad --url <website> --requested-functionality '<what was needed>' --objective '<the underlying goal of the task>' --rationale '<what happened>' --json`. Use observed results in the rationale. No job ID is needed and there is no job-age deadline. The first feedback per website each UTC day refunds 1 credit. Optional `--provider-feedback` and `--capability-feedback` JSON arrays describe specific gaps; inspect `firecrawl alexandria feedback --help` for their fields. Use the capability issue `missing_capability` when a provider exists but lacks the needed capability, and `new_capability_request` (with `requestedFunctionality`) to ask for one.
</file context>

Suggested change

To report an Alexandria session outcome or a provider/capability gap, use `firecrawl alexandria feedback --rating good|partial|bad --url <website> --requested-functionality '<what was needed>' --objective '<the underlying goal of the task>' --rationale '<what happened>' --json`. Use observed results in the rationale. No job ID is needed and there is no job-age deadline. The first feedback per website each UTC day refunds 1 credit. Optional `--provider-feedback` and `--capability-feedback` JSON arrays describe specific gaps; inspect `firecrawl alexandria feedback --help` for their fields. Use the capability issue `missing_capability` when a provider exists but lacks the needed capability, and `new_capability_request` (with `requestedFunctionality`) to ask for one.

To report an Alexandria session outcome or a provider/capability gap, use `firecrawl alexandria feedback --rating good|partial|bad --url <website> --requested-functionality '<what was needed>' --objective '<the underlying goal of the task>' --rationale '<what happened>' --json`. Use observed results in the rationale. No job ID is needed and there is no job-age deadline. The first feedback per website each UTC day can refund 1 credit, subject to the 10-credit team-per-UTC-day cap; stop sending feedback when `dailyCapReached` is true. Optional `--provider-feedback` and `--capability-feedback` JSON arrays describe specific gaps; inspect `firecrawl alexandria feedback --help` for their fields. Use the capability issue `missing_capability` when a provider exists but lacks the needed capability, and `new_capability_request` (with `requestedFunctionality`) to ask for one.

[cubic-dev-ai]

P2: The --silent & pattern below hides the response containing dailyCapReached, so callers cannot know when to stop sending feedback as instructed. Tell callers to inspect the response and avoid --silent or backgrounding when enforcing the cap.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At skills/firecrawl-alexandria/SKILL.md, line 36:

<comment>The `--silent &` pattern below hides the response containing `dailyCapReached`, so callers cannot know when to stop sending feedback as instructed. Tell callers to inspect the response and avoid `--silent` or backgrounding when enforcing the cap.</comment>

<file context>
@@ -31,11 +31,13 @@ Feedback can describe any of these outcomes:
-- **Rate honestly:** `good` when a tool answered the need, `partial` when it answered some of it or with gaps, `bad` when nothing available answered it or what ran was wrong or failed.
+- **Rate honestly:** `good` when a tool answered the need, `partial` when it answered some of it or with gaps, `bad` when nothing available answered it or what ran was wrong or failed. Every rating gets the same refund.
+- **One refund per website per UTC day.** More feedback for the same website that day is still recorded, with `alreadySubmitted: true` and no refund.
+- **Daily refund cap (per team, per UTC day, default 10 credits).** Past the cap, feedback is still recorded but refunds nothing. The response includes `creditsRefundedToday`, `dailyRefundCap`, and `dailyCapReached`. **When `dailyCapReached: true`, stop sending Alexandria feedback for the rest of the UTC day.**
 - **`--silent &`** is the right pattern: exit code 0 even on failure, so a rejected call never crashes your pipeline.
 
</file context>

Suggested change

- **Daily refund cap (per team, per UTC day, default 10 credits).** Past the cap, feedback is still recorded but refunds nothing. The response includes `creditsRefundedToday`, `dailyRefundCap`, and `dailyCapReached`. **When `dailyCapReached: true`, stop sending Alexandria feedback for the rest of the UTC day.**

- **Daily refund cap (per team, per UTC day, default 10 credits).** Past the cap, feedback is still recorded but refunds nothing. The response includes `creditsRefundedToday`, `dailyRefundCap`, and `dailyCapReached`. **When `dailyCapReached: true`, stop sending Alexandria feedback for the rest of the UTC day. To enforce this limit, inspect the response and do not use `--silent` or background this call.**

[cubic-dev-ai]

P2: alreadySubmitted can be true when the website’s first feedback arrived after the team cap was exhausted, so no credit was refunded. Say the website was already submitted today rather than claiming it was refunded.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/commands/feedback.ts, line 368:

<comment>`alreadySubmitted` can be true when the website’s first feedback arrived after the team cap was exhausted, so no credit was refunded. Say the website was already submitted today rather than claiming it was refunded.</comment>

<file context>
@@ -357,10 +357,17 @@ export async function executeEndpointFeedback(
-    lines.push('Feedback already submitted for this job.');
+    lines.push(
+      endpoint === 'alexandria'
+        ? 'Feedback recorded; this website was already refunded today.'
+        : 'Feedback already submitted for this job.'
+    );
</file context>

Suggested change

	? 'Feedback recorded; this website was already refunded today.'
	? 'Feedback recorded; this website was already submitted today.'

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 3 unresolved P0–P2 issues from previous reviews.

Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 8 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 3 unresolved P0–P2 issues from previous reviews.

Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

1 existing issue remains and no new issues found across 4 files (changes from recent commits).

Confidence score: 4/5

• alexandria-feedback.ts can keep feedback eligible based on a teammate’s recent Alexandria call, even when the user’s own call was over two minutes ago. Make the feedback-window wording reflect the team-wide rule.

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 3 unresolved P0–P2 issues from previous reviews.

Turn on auto-fix | Re-trigger cubic</sub>

[nickscamara]

Added: Alexandria feedback now has the search feedback time window (~2 minutes after the team's latest Alexandria search, discovery, or execution; later feedback gets 409 FEEDBACK_WINDOW_EXPIRED). Server side: firecrawl/firecrawl#4982 — merge that first.