Almanac

Property operations on Google Drive. A mobile-friendly, source-grounded front end for the property records you already keep in Google Drive and a master spreadsheet.

A personal project, originally built for a friend's property workflow and shared as-is — no warranty or support promised.

All included records, emails, property names, owners, vendors, and Google URLs are sample data unless you replace them in your own private environment.

Operator Self-Run Handoff

If an operator is running this from scratch with Claude, Codex, or another coding assistant, start with:

• OPERATOR_START_HERE.md for the operator.
• BOT_HANDOFF.md for the coding assistant.
• docs/operator-env-reference.md for environment variables.

Create a clean handoff archive with:

npm run handoff:operator

The archive is written under build/almanac-self-host-handoff and excludes secrets, local databases, node_modules, build output, and Vercel local state.

Open-Source Release Track

The public name is Almanac (tagline "Property operations on Google Drive"), pending a final domain and trademark check. The public landing page lives at /open-source; it is separate from the authenticated app dashboard at /.

See docs/security-review.md for scrub status, security controls, and release risks. Detailed release and market-positioning notes are kept in the operator's private working copy, not in the public repository.

Alpha Scope

• Today dashboard
• Houses indexed from the master spreadsheet
• Search across property rows, vendors, templates, generated documents, Drive metadata, and indexed document snippets
• Source-grounded assistant
• Vendors
• Financial, materials, and projects index views
• Document templates
• Generated Google Doc/PDF history
• Local Google mock mode
• Real Google OAuth, Sheets, Drive, Docs, and optional Calendar/Gmail metadata diagnostics when credentials are configured

Source Of Truth

• The master spreadsheet owns property and tenant data.
• Google Drive owns files and folders.
• The app database is an index/cache and activity log.
• The app should not become duplicate storage for the operator's business records.

Alpha Workflow

1. Sync or seed master spreadsheet rows into the local index.
2. Sync or seed Google Drive file metadata and supported document snippets into the local index.
3. Open Houses to view one page per spreadsheet-indexed property.
4. Use Search or Assistant to find property facts, Drive files, and indexed document contents.
5. Add a document template with placeholders such as {{tenant_name}}.
6. Open Documents, choose a template and spreadsheet-indexed property, then generate a copy.
7. Review the generated document in the app.
8. Use Review / print to open a printable browser view.

Local Setup

Prerequisites: Node.js 20+ and the sqlite3 command-line tool (preinstalled on macOS and most Linux distributions; install with apt-get install sqlite3 if missing). npm run db:init uses sqlite3 to apply the local migration SQL.

1. Copy .env.example to .env.
2. Keep AUTH_MODE=alpha for local single-user testing.
3. Keep GOOGLE_MODE=local for local mock testing.
4. Leave OPENAI_API_KEY blank to use the deterministic local assistant.
5. Run npm install.
6. Run npm run db:init.
7. Run npm run dev.

Hosted Auth Setup

The app has Clerk wiring behind AUTH_MODE=clerk. For a hosted alpha, configure Clerk in restricted or invitation-only mode, add the alpha tester and operator as invited users, set ALMANAC_ALLOWED_EMAILS to the comma-separated invited emails, and set the Clerk environment variables from .env.example.

Run the readiness check before inviting the operator:

vercel env pull .env.local --environment=production
npm run alpha:readiness
npm run alpha:clerk-access
npm run alpha:fixture-bundle
npm run alpha:google-oauth
npm run alpha:hosted-smoke

The pull command refreshes the ignored local env file with the hosted Production settings. The readiness command checks those Vercel-pulled environment variables and the sample fixture files. It reports blockers, warnings, and manual checks without printing secret values.

The Clerk access command checks live Clerk users and invitations against ALMANAC_ALLOWED_EMAILS. Clerk restricted mode still needs a dashboard confirmation because the Clerk Backend API used here does not expose that setting as a read-only check.

The fixture bundle command creates build/almanac-test-portfolio-upload with the sample Drive files, an upload checklist, and a manifest for manual Google Drive setup.

The Google OAuth command prints the exact Google Cloud APIs, redirect URI, and Vercel env commands needed to clear the hosted Drive/Docs blocker. It exits nonzero until GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are configured.

After the operator's real email is added to ALMANAC_ALLOWED_EMAILS, dry-run the Clerk invite before sending it:

vercel env run -e production --scope vercel-team-placeholder -- sh -c 'npm run alpha:invite-user -- --email [email protected]'

Add --send only after the dry run says the address is ready.

After Google OAuth is configured, npm run alpha:hosted-smoke confirms that the production site is Clerk login-gated, /sign-in is reachable, and the setup page points to the beta smoke-test checklist.

Hosted Database Setup

Local development uses SQLite by default. Hosted Vercel testing should use a managed Postgres database such as Neon:

DATABASE_PROVIDER=postgres npm run db:generate
DATABASE_PROVIDER=postgres npm run db:push:postgres

Set DATABASE_PROVIDER=postgres and the managed Postgres DATABASE_URL in Vercel before deploying the hosted alpha.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗