PermitGuard — User Manual

PermitGuard watches your short-term rental permits so you don't have to. Enter each property once, and it tracks every permit's expiration date, emails you at 90, 60, 30, and 7 days before a renewal is due (and again if a permit lapses), and keeps the city's renewal steps, fees, and portal links one click away.

This manual is written for the person actually running the rentals — an owner, office manager, or co-host. No technical background is assumed. All screenshots show fictional demo data.

Fastest way to learn the app: sign in and click the round ? button in the top bar. Question-mark markers appear next to buttons and status badges across the app — hover (or tap) any of them for a plain-language explanation of what that control does. Click the ? again to turn the markers off.

Quick answers

• How do I add my first property?
• How do I get renewal alerts?
• What do the green / yellow / red statuses mean?
• How do I check a permit against the city's records?
• How do I track a permit PermitGuard doesn't know about?
• How do I get text (SMS) alerts?
• How do I prove what I did and when?
• What does it cost?
• Which cities are covered?
• How do I change my password or turn on two-factor login?

1. What PermitGuard does

Four words cover the whole app:

• Listing — one rental property (a house, condo, or unit). You add these.
• Permit — a license or registration the city requires for that listing, with an expiration date. PermitGuard pre-loads the required ones for covered cities; you fill in your permit number and expiration date.
• Alert — an email (and, on paid plans, a text for urgent cases) that fires before a permit expires, when a night cap is close, or when a tax filing is due.
• Compliance — the green / yellow / red rollup on the dashboard telling you whether anything needs attention right now.

Renewal checks run automatically every morning. You can also run one any time with the Check Renewals Now button on the dashboard.

2. Signing in and getting around

• Create an account at Sign up with your email and a password (8+ characters), or use Sign up with Google. Every new account starts a 14-day free trial — no card required.
• Forgot your password? Use the Forgot password link on the sign-in page and a reset link is emailed to you.
• The left sidebar has everything: Dashboard, Listings, Permits, Calendar, Alerts, Cities, Billing, Settings, Feedback. On a phone, the sidebar becomes a menu behind the ☰ button.
• Top bar, right side: the ? hover-help toggle, the Help link (this manual), Feedback, and the dark/light mode switch.

3. The Dashboard

Your at-a-glance answer to "is anything about to bite me?"

From top to bottom:

• Total Listings — how many properties you're tracking.
• Compliant — the share of your listings whose permits are all valid and not expiring within 30 days. The small bar breaks it down: green (compliant), yellow (expiring soon), red (expired).
• Upcoming Renewals — permits expiring within the next 90 days.
• Overdue — permits that have already expired. Clear these first: operating on a lapsed permit risks fines of $500–$2,000 per day in enforcement-heavy cities, and platform de-listing.
• Renewal Timeline — every permit due in the next 90 days, soonest first. The bar fills and turns red as the deadline approaches.
• Your Listings — each property with its compliance badge and days until its next renewal. Click one to open it.
• Recent Alerts — the latest alerts sent or scheduled.
• Check Renewals Now (top right) — re-scores every listing against today's date and creates any due alerts on the spot. The same check runs automatically every day, so this is optional.
• Export CSV — downloads every listing and permit with statuses and renewal dates. A tidy compliance record for your files or your accountant.

What the colors mean

Everywhere in the app, permit status follows one rule:

• Green / Valid — expiration date is more than 30 days away.
• Yellow / Expiring — due within 30 days. Time to start the renewal.
• Red / Expired — past its expiration date. Act now.
• Gray / Unknown or Pending — no expiration date entered yet. Open the listing and add one so alerts can fire — PermitGuard can't warn you about a date it doesn't have.

4. Adding and managing listings

Listings is where properties live.

To add a property: click + Add listing, enter a name (e.g. "Barton Springs Bungalow"), the street address, city, and state. Everything else is optional. When the city is one of the covered cities you'll see "✓ … is supported — permit rules will be auto-loaded", and on save PermitGuard automatically attaches every permit that city requires — with its fee, renewal window, official renewal steps, and city portal link.

If your city isn't covered yet, the listing is still tracked — use custom permits to add its permits by hand.

To edit or remove: open the listing, then Edit listing (name, address, links) or Delete listing. Delete asks "Are you sure?" first — it permanently removes the listing with its permits and alert history.

5. Inside a listing

Click any listing to see everything the city expects of it.

Operating compliance (shown when the city has such rules):

• Annual night cap — some cities limit how many nights per year you may rent (e.g. Portland Type B: 95 nights). Keep "Nights booked this year" up to date; at 80% of the cap you get a warning alert.
• License number on listing — some cities require your permit number to be visible on the Airbnb/VRBO listing itself, or the platform must de-list you. Tick the checkbox once it's posted; PermitGuard reminds you until you do.

Compliance Check — every permit the city requires, with status, annual fee, renewal window, days left, numbered renewal steps, and a "Renew at city portal" link. Cities verified against a live public registry show an Auto-verified badge; others show the manual-check mode. "Last reviewed" is when we last re-confirmed the city's rules against official sources.

Permits — the permits actually tracked on this listing. For each one you can edit the permit number and dates, see its alert history, and:

Verify now — checking a permit against city records

Click Verify now on a tracked permit to check it against the city's official public registry.

• Austin, New Orleans, and Seattle return a live result and stamp "Last verified".
• Austin caveat: the city's public dataset hides house numbers, so a "found" result means a licensed STR of that type is on file on your street + ZIP — it is not an exact-address confirmation. Confirm your exact unit and expiration on the Austin portal.
• All other cities open a guided manual check with a direct link to the city's lookup page.

Custom permits

Add a custom permit tracks anything PermitGuard doesn't pre-load: HOA approval, liability insurance certificate, fire safety inspection, business license, and so on. Give it a name and an expiration date and it gets the same 90/60/30/7-day alert ladder as city permits. Custom permits show a blue Custom tag.

Documents — a per-listing vault for links to your permit PDFs, inspection certificates, insurance, and tax receipts (paste links from Google Drive, Dropbox, etc. — files are not uploaded to PermitGuard). Everything's in one place at renewal or audit time.

Notes — free-form notes on the listing ("Inspector prefers mornings", "Renewal receipt #12345").

6. The Permits page

Every permit across all listings in one sortable table. Filter by Expired / Expiring / Valid / No date, click a column heading to sort, and click any row to jump to its listing. "No date" is the important filter: those permits can't generate alerts until you add an expiration date. You can also add a custom permit from here.

7. The Calendar

A month view of everything with a date:

• Amber entries — permit expirations.
• Blue entries — occupancy-tax filing deadlines, for cities where you must self-remit lodging tax on direct bookings.

Below the month grid, Next 60 days lists everything coming up, soonest first. Click any entry to open its listing.

8. Alerts

PermitGuard's whole job is to warn you early, then keep warning you.

When alerts fire (all by email):

• 90, 60, 30, and 7 days before each permit expires — with the renewal steps, fee, and portal link in the email.
• On expiration — if a permit lapses.
• Night cap — when a listing reaches 80% of its city's annual night limit.
• Tax filing — about 14 days before an occupancy-tax deadline in cities with a filing schedule.
• License display — reminders until you confirm your permit number is shown on the platform listing.

Snooze vs Dismiss: Snooze hides an alert for 3, 7, or 14 days, then it returns. Dismiss clears it permanently. Neither renews anything — after you renew a permit, update its new expiration date on the listing and the alerts stop on their own.

Text (SMS) alerts

On paid plans, add your mobile number (on the Alerts page or in Settings) and tick Text me renewal alerts. Texts are sent at every renewal window — 90, 60, 30 and 7 days before expiry, and on the day a permit lapses — mirroring the email ladder. You get one text per window per permit and never more, even if a send is retried. Reply STOP to any text to opt out.

SMS requires a paid plan at the moment the text is sent: if a subscription lapses back to free, texts stop even if the toggle is still on.

9. Audit log

Audit log in the sidebar is an append-only record of everything that happened to your listings and permits — with a timestamp on every line. Nothing in PermitGuard edits or deletes an entry, which is what makes it usable as evidence when a city, a platform, or an insurer asks what you knew and when.

It records:

• Your changes — listings added, edited (with the old and new value of each field), or deleted; permit numbers and expiration dates changed; documents added or removed.
• What PermitGuard did — every renewal notice actually emailed or texted to you, and when. These are only written on a real delivery: a notice that failed to send is never recorded as sent.
• Your decisions — alerts you dismissed or snoozed, and for how long.

Each entry is labelled by you or by PermitGuard so it's clear who acted.

• Filter by listing to get the trail for one property. Each listing's own page also shows its recent Audit trail near the bottom.
• Export CSV downloads the trail (up to the 200 most recent entries) for your records or your accountant.
• Deleting a listing does not erase its history — the entries remain, so the record that it existed and was removed survives.

10. Cities and coverage

PermitGuard covers 14 US cities: Austin TX, Nashville TN, Denver CO, Portland OR, San Diego CA, New York NY, Chicago IL, Boston MA, Miami Beach FL, San Francisco CA, Honolulu HI, Los Angeles CA, New Orleans LA, and Seattle WA.

• The Cities page (and the public coverage page) lists each city's permit types, fees, renewal windows, and official portal links — read straight from the live database, so it's always current.
• Live registry verification is available in Austin, New Orleans, and Seattle; other cities use a guided manual check.
• City rule sets are automatically checked every month for staleness and broken portal links, and re-verified when anything is flagged.
• In a city we don't cover, you can still track every permit yourself with custom permits.

11. Billing and pricing

• $29/month covers your first 3 active listings — unlimited permits on each.
• Each active listing above 3 adds $9/month. (10 listings = $92/mo, 20 = $182/mo.)
• Every account starts with a 14-day free trial, no card required. When the trial ends, your data stays put, but adding new listings is paused until you subscribe.
• The Billing page shows your current plan, trial days remaining, and a live total based on your listing count. Add payment method opens secure Stripe checkout; Manage subscription opens the Stripe portal to update your card or cancel — PermitGuard never sees your card number.

12. Settings and security

• Profile — change your display name. Your login email is fixed (contact support to change it).
• Password — change it with your current password. If you've forgotten it, sign out and use Forgot password instead.
• Two-factor authentication — optional but recommended. Scan a QR code with a free authenticator app (Google Authenticator, 1Password, Authy); after that, sign-in asks for a 6-digit code from your phone. You get one-time backup codes in case you lose the phone.
• SMS alerts — the same text-alert preferences as on the Alerts page (paid plans; every renewal window).

13. On your phone

PermitGuard works in your phone's browser — the sidebar becomes a menu behind the ☰ button, and everything else works the same.

14. Getting help

• ? toggle (top bar) — turns on hover help: little question marks next to buttons and badges, each explaining in plain language what that control does.
• Help (top bar) — this manual.
• Feedback (top bar or sidebar) — send us a bug report or a question straight from the app; we reply by email.

15. Technical appendix (for operators)

Everyday users can stop reading here. This section is for whoever operates the deployment.

• App runs on port 7021 under pm2 (permitguard), Next.js App Router, Postgres via Prisma.
• Auth is MartelloAuth (credentials + Google), with optional TOTP 2FA and self-serve password reset. SKIP_AUTH=true in .env.local bypasses auth in local dev only.
• Email is delivered via Brevo and SMS via Twilio, both routed through the keys-gateway (no provider API keys on this box). If a provider isn't provisioned, sends are logged and reported as not delivered — never falsely marked sent.
• Renewal checks run daily at 08:00 UTC via cron (agents/run-renewal-check.sh → /api/cron/check-renewals, Bearer CRON_SECRET). The dashboard's "Check Renewals Now" runs the same engine on demand via session auth. The engine warms the Neon connection with a short backoff first — a cold start previously killed the whole run (2026-07-14) and skipped that day's alerts.
• SMS cost controls (src/lib/alert-engine.ts): texts fire on all five renewal windows, but only when smsAllowedForHost() passes — paid plan re-checked at send time (not just when the toggle is saved), host opted in, phone on file. An alert row texts at most once ever (Alert.smsSentAt), so an email retry can't re-text. Undelivered texts are logged and counted in smsErrors, never recorded as sent.
• City-data freshness is reviewed monthly (scripts/run-city-review.sh, 1st of the month): flags rule sets older than 90 days and broken portal/registry URLs into agents/city-review-report.md. Fixes go into prisma/seed.ts, then npm run db:seed (idempotent upsert; restamps lastReviewedAt).
• Live registry verification uses public Socrata datasets (Austin, New Orleans, Seattle) — see src/lib/scrapers.ts. Austin matches street + ZIP because the dataset redacts house numbers.
• Billing is Stripe: $29/mo base + $9/listing above 3, 14-day trial tracked on Host.trialEndsAt; after trial, POST /api/listings returns 402 until subscribed.
• Demo/screenshot data: npx tsx scripts/demo-seed.ts creates a fully fictional host (demo@permitguard.us); --purge removes it. Never screenshot real customer data.
• This manual is rendered in-app at /help from USER-MANUAL.md at the project root.