feat(account): expose quota status and quota-over-subscription precedence to agents

[pcfreak30]

Adds account_quota to the operation catalog, surfacing upload/download/storage usage and a derived has_quota signal on the CLI (pinner account quota) and the MCP tool surface. Wires quota into pinner://account/status and the auth service's GetQuota.

Encodes the "quota trumps a subscription" access rule in the agent guide and prompt templates: proceed when has_quota is true regardless of subscription; only when quota is exhausted fall back to account_subscription and surface the subscription deep-link to the human.

---

Summary

This pull request introduces a new account_quota operation across the CLI, MCP, and agent guide surfaces. It exposes the user's quota status (upload, download, storage usage/limits/remaining) and establishes a clear access policy: quota trumps a subscription — if the user has any usable quota remaining, no subscription is required and agents should proceed without asking about one. Only when quota is exhausted should agents fall back to checking subscription status, and if not subscribed, they must surface the returned web-app deep-link for the human to subscribe (agents cannot subscribe on their behalf).

Key Changes

New account_quota operation (CLI + MCP)

• Added a new catalog operation account_quota that fetches per-dimension quota (upload, download, storage) via AuthService.GetQuota and derives a has_quota boolean (true if any dimension is unlimited or has positive remaining allowance).
• Returns a typed AccountQuotaResult with has_quota, per-dimension usage/limits/remaining/reserved/threshold/percentage, a human-readable message, and the web-app web_url deep-link for managing usage/subscribing.
• Registered the new operation in AccountOperations alongside account_info, account_subscription, etc.

Auth service extension

• Added GetQuota(ctx) to the AuthService interface and implemented it in AuthServiceDefault by calling the portal SDK's client.GetQuota(ctx).

CLI wiring

• Added a CLI-only --open flag for account_quota to open the usage page in a browser (same pattern as account_subscription).
• Added human-readable rendering for quota results (e.g., upload used=5 limit=100 remaining=95 (5%)), plus the covered/not-covered message and web URL.
• JSON output paths return the full typed result including web_url and has_quota.

MCP surface

• Replaced the previous Quota(ctx) no-op (returned nil via TODO) in the MCP accountStatusAdapter with a real implementation that calls GetQuota and returns a structured map (has_quota, upload, download, storage) under the pinner://account/status resource. On error, it returns an error key so the agent can see why quota is unavailable.

Agent guidance and prompt templates

• Added a new agent-guide rule: "Access policy (quota trumps a subscription)" instructing agents to consult account_quota before paid/metered actions, proceed if has_quota is true, and only check subscription + surface web URL when quota is false.
• Updated the ens_publish_auth_status, setup_auth_status_check, and website_auth_status prompt templates with matching access-verification instructions (check quota first; only fall back to subscription when quota is exhausted; never subscribe for the human).

Tests

• Added tests for accountQuota covering: typed result with positive remaining → has_quota=true; all dimensions exhausted → has_quota=false; unlimited (nil remaining) → has_quota=true; service error propagation with account_quota: prefix.
• Added a CLI wiring test verifying account_quota --json --open emits valid JSON with web_url and has_quota and no browser chatter on stdout.
• Updated the MockAuthService with GetQuota expectations, and created a fakeAccountQuotaDeps helper for hermetic testing.

Cosmetic cleanup

• Normalized struct field alignment in several existing catalog operation specs (whitespace-only changes, no functional impact).

[github-actions]

Code Coverage Report

Total Coverage: 50.1%

Generated from commit: deafc99
Repository: LumeWeb/pinner-cli

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​