chore: configure vendored repos/effect subtree (agent reference)

Follows the Effect "git subtree" trick: vendor the Effect v4 source as
read-only reference so agents read real source (the published Effect docs
are v3 and wrong for the beta this project targets). The subtree itself was
added in the preceding commit (git subtree add --prefix=repos/effect from
Effect-TS/effect-smol main --squash).

This commit wires the supporting config so repos/ stays invisible to humans
and tooling:
- AGENTS.md: documents repos/effect as read-only reference + the v3→v4 API map
  and the high-value Schema.ts/SchemaAST.ts files to consult.
- .vscode/settings.json: exclude repos/** from auto-imports, search, watch
  (un-gitignored just this file so the config is shared).
- .prettierignore + eslint.config.mjs: ignore repos/** (keeps lint/format fast
  and off the 31M vendored tree).

repos/ is already absent from tsconfig include and the npm `files` allowlist,
so it is neither compiled nor published (verified: typecheck/build/test:emit
green, npm pack has 0 repos/ entries).

Update with: git subtree pull --prefix=repos/effect <effect-smol> main --squash

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: samuelho-dev

.gitignore

@@ -11,7 +11,9 @@ coverage/
 *.lcov
 
 # IDE
-.vscode/
+.vscode/*
+# but share the repos/ editor excludes for the vendored subtree (see AGENTS.md)
+!.vscode/settings.json
 .idea/
 *.swp
 *.swo

.prettierignore

@@ -13,6 +13,9 @@ coverage/
 src/test-output*/
 src/__tests__/generated/
 
+# Vendored read-only Effect v4 source (git subtree, agent reference only)
+repos/
+
 # Git
 .git/
 

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "//": "repos/ is vendored read-only reference source (git subtree). Keep it out of editor auto-imports, search, and file watching so it never leaks into project code or slows the editor.",
+  "typescript.preferences.autoImportFileExcludePatterns": ["repos/**"],
+  "javascript.preferences.autoImportFileExcludePatterns": ["repos/**"],
+  "search.exclude": {
+    "repos/**": true
+  },
+  "files.watcherExclude": {
+    "repos/**": true
+  }
+}

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository. (See `CLAUDE.md` for the
+full project reference — commands, architecture, the Effect 3→4 migration notes,
+and the v4 API map. This file documents the vendored reference source.)
+
+## Vendored reference source
+
+This project vendors external source under `repos/` as **read-only reference
+material** (via `git subtree`, not a submodule — no init needed).
+
+- Use vendored source to learn idiomatic usage; never import from it or edit it.
+- Prefer patterns from the vendored source over documentation or web search —
+  the published Effect docs are for Effect 3 and are **wrong** for the Effect 4
+  beta this project targets. The vendored source is the source of truth.
+- `repos/` is excluded from TypeScript compilation, ESLint, Prettier, and the
+  npm package (`files` allowlist). Do not add it to any `include`/`files` list.
+
+### `repos/effect/` — Effect v4 source (vendored from `Effect-TS/effect-smol`, branch `main`)
+
+`effect@4.0.0-beta.x` is built from the `effect-smol` monorepo. When writing or
+reviewing Effect code, inspect `repos/effect/packages/effect/src` (and
+`.../test`) for real v4 API shapes, signatures, and idioms — do not infer them
+from memory or v3 docs.
+
+High-value files for this generator:
+
+- `repos/effect/packages/effect/src/Schema.ts` — `Top`, `Bottom`, `Codec`,
+  `Struct`, `brand`, `check`, `encodeKeys`, `Enum`, the `is*` filters. This is
+  the file to consult for any `Schema.*` question. (`Top` is the structural base
+  every schema must satisfy; `Bottom<...>` is its 15-param shape.)
+- `repos/effect/packages/effect/src/SchemaAST.ts` — AST node types (`Objects`,
+  `PropertySignature`, `resolve`, the `is*` guards). v4 reworked this heavily
+  from v3.
+
+### Effect 3 → 4 quick map (verified against the vendored source)
+
+- `Schema.Schema<T,E,R>` → `Schema.Codec<T,E,RD,RE>`; `Schema.Schema.All` →
+  `Schema.Top`; `Schema.Schema.Type<S>` → `Schema.Schema.Type<S>` (kept);
+  `Schema.Codec.Encoded/DecodingServices/EncodingServices<S>` for the rest.
+- `asSchema` → `revealCodec`; `.annotations({})` → `.annotate({})`.
+- `Schema.DateFromSelf` → `Schema.Date`; `Schema.UUID` →
+  `Schema.String.check(Schema.isUUID())`; `Schema.BigIntFromSelf` → `Schema.BigInt`.
+- Filters moved under `.check(Schema.is*)` (e.g. `Schema.int()` →
+  `Schema.check(Schema.isInt())`, `Schema.between(a,b)` →
+  `Schema.check(Schema.isBetween({ minimum, maximum }))`).
+- Variadic combinators take arrays: `Schema.Union(a,b)` → `Schema.Union([a,b])`,
+  `Schema.Literal(a,b)` → `Schema.Literals([a,b])`, `Schema.Tuple(...)` → array.
+- `Schema.Enums` → `Schema.Enum`; `Schema.propertySignature(...).pipe(Schema.fromKey(...))`
+  → struct-level `Schema.encodeKeys({ tsName: "db_col" })`.
+
+## Updating the vendored source
+
+```bash
+git subtree pull --prefix=repos/effect https://github.com/Effect-TS/effect-smol.git main --squash
+```
+
+Keep it roughly in sync with the `effect` beta the project pins (`devDependencies.effect`).

eslint.config.mjs

@@ -61,6 +61,8 @@ export default tseslint.config(
       '**/*.d.ts',
       'src/test-output*/**',
       'src/__tests__/generated/**',
+      // Vendored read-only Effect v4 source (git subtree, agent reference only)
+      'repos/**',
     ],
   }
 );