Slug: fedm8 (new surface inside the existing app) · Lane: gated · Author: 1099:anthropic-cowork-vetdir1 · Date: 2026-08-12
Build a directory inside FedM8 where a disabled veteran can find and choose someone to help with a VA disability claim, see both a Google star rating and a FedM8 rating from other veterans, read reviews written only by identity-verified veterans, and where firms can pay a subscription to appear above organic results as Sponsored.
The plan below implements the scope as specified, including listing unaccredited claim consultants with an accreditation badge and a pay-per-lead pricing tier. Three parts of that specification carry legal exposure large enough that they are called out as decision gates rather than buried as risks — see §9. Phases 0–4 are unaffected by those gates and can start immediately.
Four findings materially reshaped the design. Each is load-bearing.
1.1 ID.me cannot verify an honorable discharge. ID.me's community payload is {group: "military", subgroup: "Veteran"} — there is no discharge-characterization attribute, and several documents it accepts (a veteran-endorsed driver's licence, a VHIC card) establish served, not honorable. SheerID states in writing that its instant sources "do not differentiate on discharge status." VerifyPass and GovX are affiliation-only. The only programmatic source of discharge characterization is VA's Veteran Service History and Eligibility API (service_history.read) under the veteran's own OAuth consent. That API is free but requires a written application, a live demo to VA, published ToS and privacy policy URLs, a documented breach process, and 1–6 months of review — against a standing VA banner warning of long delays. The design therefore separates verified veteran (fast, cheap, ships now) from honorable-verified (slow, gated on VA approval) and never claims the second while only holding the first.
1.2 Google star ratings cannot be stored. Maps Platform Service Specific Terms §14.3 permits caching latitude and longitude only, for 30 days. Ratings, review counts, review text, author data and photos are outside the exception. place_id may be stored indefinitely. So there is no google_rating column — ever. Google ratings are fetched live at render time, cached in-memory for the request only, attributed with the Google Maps mark, visually segregated by a border or background, and never blended into a FedM8 composite score. If the Places call fails, the card renders with the FedM8 rating alone.
1.3 The prohibition on unaccredited paid assistance is real but federally penalty-less — and the states have filled the gap. Only VA-accredited attorneys, claims agents and VSO representatives may assist; only agents and attorneys may charge, only for work after the AOJ's initial decision, at ≤20% of past-due benefits presumed reasonable. 38 U.S.C. §5905's criminal clause covering unlawful fee-charging was struck in 2006, which is why unaccredited consultants operate openly. Enforcement in 2026 runs through state AGs and private suits: Texas took $6.8M in debt relief from VA Claims Insider in January 2026; Arizona settled with VetLink for ~$2M in May 2026; California SB 694 was signed February 2026 with penalties starting 2027; New York's GUARD Act carries $10,000 per violation plus a private right of action. A district court in North Carolina held in May 2026 that Veterans Guardian acted as an unaccredited agent and violated federal law by charging. Countervailing: the Third Circuit in Veterans Guardian v. Platkin (Apr 2025) found these services likely constitute protected speech, and a Louisiana federal court struck that state's fee-cap law in February 2026. The law is genuinely unsettled and moving in both directions.
1.4 Pay-per-lead is a different legal object than a subscription. A flat listing fee is advertising and is permitted essentially everywhere. Per-lead pricing invites three separate problems: ABA Model Rule 7.2(b) and the NJ ACPE 741 "disguised referral" factors; state runner/capper statutes (Texas barratry is a third-degree felony and reaches the paying lawyer as well as the platform; Louisiana R.S. 37:219 carries up to five years); and California Business & Professions Code §6155, which makes it unlawful to operate a lawyer referral service in California without State Bar registration — the single most likely trap for a matching directory. Risk rises with per-lead price, screening/qualification, and exclusivity.
Three surfaces on ai.fedm8.com, kept out of the GovCon scanner's nav:
| Surface | Who | What |
|---|---|---|
/find | veterans, logged out | search + filter firm list, sponsored block above organic |
/firm/:slug | veterans | profile, both ratings, reviews, contact |
/for-firms | firms | claim listing, subscribe, respond to reviews, lead inbox |
Veteran journey: land → filter (state, accreditation type, language, fee model, remote OK) → compare cards → open profile → read verified reviews → contact. Contact is the conversion event, not a purchase. No account required to read; account + verification required to review.
Firm journey: find own listing (pre-seeded from the VA OGC accreditation roster) → claim it via domain email or phone → verify → free profile → optional paid tier.
Design commitments that fall directly out of §1:
block sits above it in a visually distinct container, each item labeled Sponsored (not "Featured," not "Top Pick," not "Partner"), label above the block and on each card.
The FTC's LendEDU action (2020, $350k plus a permanent bar) is precisely a comparison site that sold placement while implying objective rankings.
The ranking methodology is published at /find/how-ranking-works.
oeohvlajtexuxjfrtcdb, schema directory)firm id, legal_name, dba, slug, kind, website, phone, address,
google_place_id, state_codes[], languages[], remote_ok,
claimed_by, status, created_at
-- kind: attorney | claims_agent | vso_rep | vso_org | consultant
-- NO google_rating / google_review_count columns. Ever. (§1.2)
accreditation id, firm_id, person_name, va_accreditation_number, kind,
first_accredited_on, source_roster_date, verified_at, is_current
-- refreshed from the VA OGC Excel roster (Mon/Wed/Fri evenings)
fee_practice firm_id, charges_pre_decision bool, fee_basis, max_pct,
files_fee_agreement_with_ogc bool, self_attested_at, evidence_url
veteran id, auth_user_id, verification_level, verified_at, provider,
provider_subject_id, state_code
-- verification_level: none | identity | veteran | veteran_honorable
-- NO SSN. NO DD-214 images. NO discharge document storage. (§4)
review id, firm_id, veteran_id, rating_1_5, body, outcome_tag,
engagement_attested_at, status, published_at, edited_at,
moderation_reason, firm_response, firm_response_at
-- status: pending | published | rejected | withdrawn
firm_rating_daily firm_id, day, n_reviews, mean_rating, bayesian_rating
-- FedM8 rating only. Bayesian shrinkage toward the global mean.
subscription firm_id, tier, stripe_subscription_id, status, started_at,
sponsored_states[], sponsored_slots
lead id, firm_id, veteran_id, channel, created_at, billable,
state_code, disposition
-- disposition is veteran-reported only; NEVER firm-reported retention
audit_event actor, entity, entity_id, action, before, after, atRLS: every table on, policies written so read and write scope agree — the NodeDough cross-household bug came from reads gating on visibility while writes gated on membership. revoke truncate on … from anon, authenticated on every new table. directory is not exposed to the Data API; the browser reaches it through curated public.dir_* views and RPCs, matching how portfolio is handled today.
| Level | How | Badge shown | Can review |
|---|---|---|---|
identity | Supabase auth + email | none | no |
veteran | ID.me OIDC, military scope, subgroup Veteran | "Verified veteran" | yes |
veteran_honorable | VA VSHE API, service_history.read, OAuth ACG | "Verified honorable discharge" | yes |
veteran ships in Phase 2 and is the review gate at launch. veteran_honorable ships only if and when VA grants production access; until then the phrase "honorable discharge" does not appear on the site, because nothing available can substantiate it.
Hard rules: no SSN is ever collected (which rules out the Veteran Confirmation API and its state SSN-statute exposure under Cal. Civ. Code §1798.85 and equivalents). No DD-214 upload, ever — "military identification number" is an enumerated PII element in a large share of state breach-notification statutes, and a DD-214 store is a notice-triggering breach waiting to happen. Biometric matching stays inside the vendor; FedM8 never receives a biometric, contractually as well as technically (BIPA, TX CUBI, WA MHMD).
Cost signal for veteran: ID.me's published low-volume proxy is ~$1.25/verification; enterprise is custom-quoted. Budget a per-verification line item, not a flat fee.
Two ratings, side by side, never merged.
place_id, Google Maps mark attached, own bordered container, links to googleMapsUri, ranking-factor disclosure per Google's policy.
n shown alongside, "notenough reviews yet" below a threshold of 3.
Review integrity, built to 16 CFR Part 465 (effective 21 Oct 2024, civil penalty $53,088 per violation):
veteran-level accounts may post. One review per firm per veteran.conditioned on a particular sentiment, and the safest posture is no compensation at all.
blocked; detection is by email domain, phone and device fingerprint, and violations are published as removals.
subscribers and non-subscribers**: PII, defamation, obscenity, off-topic, clearly false, reasonable belief of fakery. Nothing else. Every moderation action writes an audit_event with a reason.
Suppressing negative reviews of a paying firm while implying the display is complete is the §465.7 violation and the single fastest way to turn this product into an FTC matter.
They cannot delete, and a flag never hides a review pending review.
firm for that conduct, and the log is FedM8's evidence.
Free tier (default, every accredited representative on the OGC roster): name, kind, accreditation badge, state, contact, both ratings, reviews.
Sponsored subscription (flat monthly, per state): placement in the labeled Sponsored block, logo, photos, longer description, review responses surfaced, a lead inbox, and analytics. Flat fee only, tiered by number of states and slots — no component of price varies with outcome. Billed through Stripe on the existing FedM8 Stripe account.
Pay-per-lead (specified, and gated — see §9.3): if built, it is engineered as narrowly as the research allows: fixed low per-contact price published on /for-firms; never contingent on retention, engagement, settlement or recovery; no exclusivity — every qualifying firm is shown, a lead may reach several; no qualification or scoring of the lead by FedM8 beyond the veteran's own stated state and claim stage; and the disposition field records only what the veteran reports, never what the firm reports, so no data path exists that could make price track conversion. California is excluded from per-lead pricing unless and until a §6155 lawyer-referral-service registration is obtained; Texas and Louisiana are excluded pending written outside-counsel sign-off.
Accreditation badging. Every card carries one of:
VA-accredited attorney / claims agent / VSO representative — matched against the OGCroster, with the roster refresh date shown.
Not VA-accredited — displayed in the same size and weight as the accredited badge, nota subtle grey, plus a one-line plain-English explanation and a link to VA's own guidance and accreditation search. A firm's subscription tier never softens, hides, or outranks this badge.
Free VSO service (DAV, VFW, American Legion, state veterans agencies) is presented first on every search, above the sponsored block, in a persistent module: "You can get help with this for free." This is both the right answer for the veteran and the strongest available evidence that the product is not simply a funnel to paid services.
| Phase | Deliverable | Depends on | Gate |
|---|---|---|---|
| 0 | ToS, privacy policy, security headers on ai.fedm8.com; 301 between ai. and scan. | — | none — do this first regardless |
| 1 | directory schema + RLS + dir_* views; OGC roster importer (Excel, Mon/Wed/Fri); seed accredited firms | 0 | none |
| 2 | /find + /firm/:slug read-only; live Google ratings; free-VSO module; ranking-methodology page | 1 | none |
| 3 | ID.me OIDC; veteran level; review write + moderation console + audit log | 0, 2 | none |
| 4 | Firm claim flow; free profile; firm responses | 2 | none |
| 5 | Stripe flat-fee sponsorship; Sponsored block; /for-firms | 4 | G-A (§9.1) |
| 6 | Pay-per-lead tier | 5 | G-B (§9.3) — blocked |
| 7 | VA VSHE integration; veteran_honorable badge | 0, 3 | VA production approval, 1–6 mo |
Phases 0–4 are ~4–6 focused build sessions and carry no open legal gate. Phase 5 is small engineering behind one decision. Phase 6 is small engineering behind a large decision.
Seeding. Firms are seeded from the VA OGC roster — Excel downloads of attorneys, claims agents, VSO representatives and VSOs-with-reps, refreshed Mondays, Wednesdays and Fridays. That yields a complete, authoritative accredited universe at zero acquisition cost, which is the liquidity answer for a two-sided marketplace: the veteran side is useful on day one before a single firm subscribes. Unaccredited consultants are not bulk-seeded; if listed at all they are added only on claim, so the roster's default state is the lawful one.
[PASS/FAIL] with the command + HTTP code.no persisted Google rating value — a grep of the DB for a ratings column is the test.
positive cases, as a real authenticated user with request.jwt.claims set.
criteria — unavoidable, not behind a hover, visually distinct, in close proximity.
These are surfaced rather than absorbed because each one binds the company.
9.1 — G-A: listing unaccredited consultants (specified as "list, flagged"). Listing them is legal in most states today. Taking a placement fee to rank them above accredited attorneys is the exposure: it is the conduct state AGs have been pursuing, and Texas and Arizona have already extracted $8.8M combined from two operators in 2026. The badge mitigates consumer confusion; it does not mitigate the platform's own UDAP exposure in NY (private right of action, $10k/violation) or CA (SB 694, penalties from 2027). Three options: (a) list unaccredited firms but make them ineligible for any paid tier — preserves inventory, removes the monetization link, my recommendation; (b) as specified, with per-state suppression and outside-counsel sign-off; (c) accredited-only.
9.2 — G-A2: "honorable discharge" verification. Not purchasable. Either the badge says "Verified veteran" at launch (recommended) or Phase 3 waits 1–6 months on VA.
9.3 — G-B: pay-per-lead. Texas barratry is a felony that attaches to the paying lawyer too, which means firms' own counsel will refuse the contract; California §6155 requires State Bar registration for a referral service. The flat-subscription tier captures most of the revenue with none of this. Recommendation: ship Phase 5, hold Phase 6 pending written outside-counsel opinion, and price sponsorship higher rather than adding per-lead.
9.4 — audience fit. FedM8 today is a GovCon contracts scanner for veteran-owned businesses. This directory serves individual veterans filing disability claims — a different person with a different problem. Sharing the brand is defensible; sharing the navigation will confuse both. The plan keeps the surfaces separate (§2, §5 of the project instructions).