[koniz-dev]

Refs #1130

Problem

docs/api/core/storage.md and lib/core/storage/isar_database_template.dart told an adopter to run flutter pub add --dev isar_generator. On this starter that fails version solving: every isar_generator 3.x needs source_gen 1.x, and freezed ^4 needs source_gen 3 or later.

Change

• Packages: the template and guide now use the community-maintained Isar 3 packages (isar_community, isar_community_flutter_libs, isar_community_generator 3.4.1, publisher isar-community.dev), and explain why the originals cannot be added here.
• Steps that end in a clean analyze:
  • Collections go in lib/core/storage/collections/, whose generated *.g.dart is excluded in analysis_options.yaml. Isar's generated code fails very_good_analysis.
  • On activation, delete the template's two tests.
• Platforms: stated as Android, iOS, macOS, Windows and Linux; not web. Isar 3 throws at open in the browser.
• Template code fixes, so it analyzes once uncommented: put(object) instead of put(object as dynamic), and return await inside async.
• Wording: it is no longer called "the recommended" database.
• test/docs/isar_template_setup_test.dart keeps the template and the guide on identical pub add steps and off the original packages. It fails against main's files and runs with the docs-only tests.

Verified

• The old step fails on main: flutter pub add --dev isar_generator --dry-run fails version solving.
• The new steps resolve on main (dry-run).
• Every step, followed literally in a fresh clone of this branch (f5fcb70):
  • Steps 1-2: pub add.
  • Step 3: a documented @collection Note, the exclude, and build_runner.
  • Step 4: uncomment, NoteSchema.
  • Step 5: delete the two tests.
  • Result: flutter analyze exits 0, no committed generated file changes, and flutter test test/docs test/core/storage passes.
• Not verified: running Isar needs its native library on a device or desktop. That belongs to the adopter's app.
• ./scripts/dev/audit_template.sh exits 0 on bb71872 (4126 tests); this PR's checks ran on the head.

Correction to the first version of this description: it said the activated template "analyzes clean". That check counted only errors and warnings. Under very_good_analysis, the 40+ infos on Isar's generated file make flutter analyze exit 1. The review caught it; the exclude in step 3 fixes it, and the exit code above is the real one.

Pre-merge review

A fresh reviewer subagent ran on bb71872 with the PR, issue and diff, not the implementer's verdict. The diff touches lib/core/storage/.

Fixed on this branch (f5fcb70):

• Following the steps left flutter analyze failing on Isar's generated code.
• The new test pinned the template's commented state, so it would fail after activation.
• Nothing said Isar 3 cannot run on the web.
• The guide gave no publisher to judge the fork by.

Supply chain, checked by the reviewer against pub.dev and GitHub:

• The three packages come from the verified publisher isar-community.dev, at version 3.4.1 (2026-10-13).
• Repository: isar-community/isar-community, Apache-2.0, active. Its history carries over the original Isar author.
• isar_community_flutter_libs ships prebuilt native binaries, as the original did.
• Verdict: reasonable to point adopters at.

🤖 Generated with Claude Code