docs: add contributor foundation

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.sh text eol=lf

AGENTS.md

@@ -0,0 +1,40 @@
+# Contributor instructions
+
+Before substantive work, read [product scope](docs/product.md),
+[architecture](docs/architecture.md), [data policy](docs/data-policy.md), and
+[roadmap](docs/roadmap.md). This file is the authoritative agent entry point.
+
+## Binding decisions
+
+- Gizmoduck is the clean successor to Robopato.
+- Use Python, Django, PostgreSQL, migrations from the beginning, Docker Compose
+  for local infrastructure, and pytest for automated tests.
+- Import bank accounts from CSV and Banco do Brasil/Ourocard credit cards from
+  TXT. OFX is not supported.
+- Keep parsing, normalization, validation, duplicate detection, preview, and
+  persistence separate.
+- Obtain owner approval before changing these constraints or product scope.
+
+## Working rules
+
+- Preserve user changes and avoid unrelated edits.
+- Make small, cohesive changes with verification appropriate to their risk.
+- Use isolated Git worktrees for concurrent implementation that could overlap.
+- Design and plan substantial subsystems before implementing them.
+- Report assumptions, checks performed, and unresolved risks accurately.
+- Do not perform destructive operations, pushes, merges, releases, or history
+  rewrites without explicit authorization.
+- Focused local commits are allowed after verification. Inspect both staged
+  paths and staged content for real financial data and secrets before every
+  commit. When uncertain whether data is safe, stop and ask the owner.
+- Agent-authored commits use repository-local `Codex <codex@localhost>`;
+  human-authored commits retain the human contributor's identity.
+
+## Financial data
+
+Agents may read every file in Robopato and copy real documents for local
+development, parser validation, migration, and compatibility testing. Store
+real data only in ignored local directories or local databases. Never commit
+raw data, identifying excerpts, snapshots, logs, screenshots, reports, or dumps.
+Committed fixtures must be synthetic or irreversibly sanitized. Follow the
+[full data policy](docs/data-policy.md) before handling source documents.

docs/architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+## Binding stack
+
+Use Python and Django for the application, PostgreSQL for persistent storage,
+schema migrations from the beginning, Docker Compose for local infrastructure,
+and pytest for automated tests. Changes require explicit owner approval and a
+documented architectural decision.
+
+Dependency versions and tooling will be selected in the application-skeleton
+design. This foundation does not prescribe a database schema or UI framework.
+
+## Import boundaries
+
+```text
+source document
+  -> source-specific parsing
+  -> normalization
+  -> validation
+  -> duplicate detection
+  -> preview
+  -> explicit commit and persistence
+  -> categorization and reporting
+```
+
+Bank-account parsers consume CSV; Banco do Brasil/Ourocard card parsers consume
+TXT. OFX is unsupported. Parsers are pure transformations of supplied input;
+they do not query or write the database. Normalization maps parser output into
+a common candidate representation without committing transactions.
+
+Validation reports issues for review. Duplicate detection compares candidates
+with the relevant import and persisted records through a separate boundary.
+Preview displays candidates and issues without committing financial records.
+Persistence owns database writes, migrations, and commit integrity. Parser
+grammars, candidate contracts, duplicate rules, and transaction boundaries are
+specified and tested when the import subsystem is designed.
+
+## Data and accountability
+
+Preserve import provenance. Imports and material data changes record actor,
+source, timestamp, and outcome so human, application, and automated activity can
+be distinguished. Keep sensitive audit details in local storage governed by
+the [data policy](data-policy.md).
+
+Use separate least-privilege database accounts for development and application
+processes. Credentials belong in local environment configuration, never in
+tracked source. The skeleton design must define role provisioning and migration
+permissions. Schema changes must use migrations, not manual database drift.
+
+## Delivery boundaries
+
+The financial domain model, UI, importer grammar, duplicate algorithm, deployment
+model, and backup implementation each require design before substantial work.
+Follow the [roadmap](roadmap.md) for sequencing and [product scope](product.md)
+for acceptance boundaries.

docs/data-policy.md

@@ -0,0 +1,52 @@
+# Financial data policy
+
+## Authorized local use
+
+Agents may read every file in the Robopato repository and copy real financial
+documents for local development, parser validation, migration, and compatibility
+testing. This permission does not authorize committing that material or sending
+it to external services.
+
+Real financial data may exist only in ignored local directories and local
+databases. Use these repository-root directories:
+
+| Location | Purpose |
+| --- | --- |
+| `data/` | Local working data and database storage |
+| `documents/` | Source documents copied from Robopato |
+| `imports/` | Local import inputs and intermediate results |
+| `uploads/` and `media/` | Application-managed local files |
+| `exports/` | User exports and generated reports |
+| `backups/` | Database and application backups |
+
+Verify the destination with `git check-ignore` before copying financial data.
+Keep local credentials in ignored `.env` files; `.env.example` may contain only
+non-secret examples. Keep sensitive execution output out of shared transcripts.
+
+## Git boundary
+
+Never add real financial data to Git. This includes raw documents, database
+dumps, copied excerpts, snapshots, logs, screenshots, generated reports, and
+documentation containing identifying transaction data. Ignoring a file does
+not remove data that was already tracked. Never use force-add to bypass this
+policy.
+
+Committed tests and examples must use synthetic or irreversibly sanitized data.
+Use `tests/fixtures/synthetic/` for explicitly synthetic CSV, TXT, and PDF
+fixtures. A fixture exception in `.gitignore` is not evidence that its contents
+are safe. Sanitization must remove identifying information and prevent recovery
+of the original sensitive data; changing a name alone is insufficient.
+
+Before every commit, inspect `git diff --cached --name-only` and
+`git diff --cached`, including newly added fixtures, for financial data and
+secrets. When uncertain whether material is safe, stop and ask the owner.
+
+## Runtime handling
+
+Use separate least-privilege development and application database accounts.
+Record actor, source, timestamp, and outcome for imports and material changes.
+Treat audit records, errors containing source rows, and test output derived from
+real documents as financial data. Use synthetic data for shareable diagnostics.
+
+If sensitive material is accidentally tracked, stop propagation and notify the
+owner. Do not push it or rewrite history without explicit authorization.

docs/product.md

@@ -0,0 +1,35 @@
+# Product scope
+
+Gizmoduck is a privacy-conscious personal finance application for an individual
+managing their own accounts and credit cards locally. It succeeds Robopato,
+retaining lessons from Banco do Brasil statements and Ourocard invoices without
+carrying forward notebook-driven architecture or importing historical data by
+default.
+
+## MVP
+
+- Manage bank accounts and credit cards.
+- Import bank-account CSV and Banco do Brasil/Ourocard credit-card TXT.
+- Preview parsed transactions, validation issues, and suspected duplicates
+  before committing an import.
+- Preserve provenance and detect duplicates across imports.
+- Organize transactions by payee and category.
+- Represent transfers, refunds, and installments correctly.
+- Inspect monthly cash flow and spending summaries.
+- Export and back up user-owned data.
+
+A successful MVP supports the local path from source file through reviewed
+import to understandable transactions and summaries, with tests using synthetic
+or irreversibly sanitized fixtures. A failed or cancelled preview must not
+commit financial transactions. Exact importer grammars and financial modeling
+rules require subsystem designs before implementation.
+
+## Exclusions
+
+OFX is not supported. Bank APIs, investment tracking, mobile clients, receipt
+recognition, forecasting, and AI categorization are outside the MVP. Hosted
+multi-user operation is not part of the initial local release.
+
+The owner must approve scope changes. Technical choices are defined in
+[architecture](architecture.md); financial data handling follows the
+[data policy](data-policy.md).

docs/superpowers/plans/2026-09-06-agent-foundation.md

@@ -0,0 +1,60 @@
+# Agent Foundation Implementation Plan
+
+> **For agentic workers:** Use superpowers:executing-plans to implement this plan inline, task by task.
+
+**Goal:** Establish the approved contributor guidance and privacy boundaries.
+
+**Architecture:** Keep AGENTS.md concise and authoritative. Separate product,
+architecture, data policy, and delivery sequence into linked documents.
+
+**Tech Stack:** Markdown and Git; the application will use Python, Django,
+PostgreSQL, Docker Compose, and pytest.
+
+**Spec:** [Approved foundation design](../specs/2026-09-06-agent-foundation-design.md).
+
+## Global constraints
+
+- The project is named Gizmoduck and is the clean successor to Robopato.
+- The backend uses Python and Django.
+- Persistent storage uses PostgreSQL with migrations from the beginning.
+- Local infrastructure uses Docker Compose.
+- Automated tests use pytest.
+- Bank-account transactions are imported from CSV.
+- Credit-card transactions are imported from Banco do Brasil/Ourocard TXT.
+- OFX is not supported.
+- Parsing, normalization, validation, duplicate detection, preview, and
+  persistence remain separate stages.
+- Real financial data and secrets must never enter Git.
+- Preserve existing README and ignore-file content while making targeted updates.
+
+## Task 1: Publish contributor and project guidance
+
+**Files:** Create AGENTS.md, docs/product.md, docs/architecture.md,
+docs/data-policy.md, docs/roadmap.md; update README.md.
+
+**Interfaces:** Consumes the approved spec; produces linked contributor policy.
+
+- [x] Write AGENTS.md with binding constraints, reading order, operating rules,
+  local commit identity, and links to the four project documents.
+- [x] Write product scope and exclusions, architecture boundaries, permitted
+  Robopato access and local-data locations, and milestone acceptance criteria.
+- [x] Link the documents from README and align its architecture language with
+  the approved binding choices.
+- [x] Check that every relative Markdown link resolves and review all documents
+  against the approved spec for contradictions and unresolved policy choices.
+
+## Task 2: Verify data exclusions and readiness
+
+**Files:** Update .gitignore only where approved protections are missing.
+
+**Interfaces:** Consumes data-policy locations; produces Git exclusion rules.
+
+- [x] Exclude raw financial CSV/TXT/PDF and database dump formats, keeping
+  explicitly synthetic fixture paths trackable. Preserve existing rules.
+- [x] Use git check-ignore with representative paths under each local-data
+  directory, secret and dump formats, and synthetic fixtures. Confirm raw data
+  is ignored and synthetic fixtures remain trackable without creating real data.
+- [x] Run git diff --check; verify repository-local user.name and user.email
+  equal Codex and codex@localhost; inspect changed files for secrets/data.
+- [x] Report the completed foundation and next application-skeleton milestone.
+  Leave existing user edits and new documents available for review locally.