@@ -0,0 +1,46 @@
+---
+updated: 2026-05-09
+---
+
+# Knowledge Base
+
+Accumulated learnings from this project. Read this before starting new work.
+
+## Project Patterns
+
+- IntelliJ Platform Gradle Plugin upgrades can require both Gradle wrapper updates and build script API adjustments.
+- Grammar/parser generation depends on IntelliJ Platform classpath alignment; when `generateParser` fails with missing IntelliJ classes, check Grammar-Kit and IntelliJ Platform Gradle Plugin compatibility together.
+
+## Common Pitfalls
+
+- `README.md` must contain `<!-- Plugin description -->` and `<!-- Plugin description end -->` markers because `patchPluginXml` extracts the plugin description from that section.
+- Local Gradle project caches under `.gradle` can fail on Windows with file-lock or directory-creation errors; validating in a clean temporary workspace can distinguish local cache problems from source/build-script problems.
+
+## Workflow Learnings
+
+- For build-tooling updates, verify plugin portal versions first, then run a clean build after each compatibility-driven change.
+- When a standard workspace build is blocked by local cache permissions, document the workaround and validation command in the PR.
+
+## Reflections
+
+### 2026-05-09 — Build plugin update for 2026.1
+
+**What was done**: Updated the build tooling for the 2026.1 target by upgrading the IntelliJ Platform Gradle Plugin, Grammar-Kit plugin, and Gradle wrapper. Adapted the `create()` dependency declaration to the newer API and restored README plugin-description markers required by `patchPluginXml`.
+
+**What went well**:
+- Updating Grammar-Kit and IntelliJ Platform Gradle Plugin together resolved the original `generateParser` classpath failure.
+- A clean temporary workspace build isolated source/build-script issues from local `.gradle` cache permission problems.
+- The final build passed after adapting the dependency declaration and restoring README markers.
+
+**What was harder than expected**:
+- IntelliJ Platform Gradle Plugin `2.16.0` required Gradle `9.0.0`, which introduced an API compatibility adjustment in `build.gradle.kts`.
+- The local workspace Gradle cache repeatedly failed with Windows file-lock/directory errors, so standard in-place build verification was not reliable.
+- `patchPluginXml` failed late because the README description markers were missing.
+
+**Patterns noticed**:
+- Build-tooling upgrades often reveal chained compatibility requirements: Gradle plugin version, Gradle wrapper version, DSL API, and documentation-derived metadata all need to line up.
+- Local environment failures should be separated from source failures by using a clean copy and explicit temporary cache directories.
+
+**Workflow observations**:
+- The ship flow caught the local standard-build failure, but the clean-workspace validation provided enough confidence to proceed with a documented PR note.
+- This was a quick build-tooling fix without a dedicated brainstorm; future non-trivial version migrations should start with a brief brainstorm entry before edits.
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "knowledge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "knowledgebased"]
+    }
+  }
+}
@@ -14,6 +14,8 @@
 
 ---
 
+<!-- Plugin description -->
+
 ## ✨ What It Does
 
 This plugin turns your JetBrains IDE into a protobuf-aware development environment — not just syntax highlighting, but deep understanding of your schema.
@@ -22,6 +24,8 @@ This plugin turns your JetBrains IDE into a protobuf-aware development environme
 > Not compatible with the bundled [JetBrains Protocol Buffer plugin](https://plugins.jetbrains.com/plugin/14004-protocol-buffers).
 > Disable **Protocol Buffer** and **gRPC** before installing.
 
+<!-- Plugin description end -->
+
 ## 🚀 Quick Start
 
 1. Open **Settings → Plugins → Marketplace**
 
@@ -43,7 +43,9 @@ dependencies {
 
     // IntelliJ Platform Gradle Plugin Dependencies Extension - read more: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-dependencies-extension.html
     intellijPlatform {
-        create(providers.gradleProperty("platformType"), providers.gradleProperty("platformVersion"), useInstaller = false)
+        create(providers.gradleProperty("platformType"), providers.gradleProperty("platformVersion")) {
+            useInstaller = false
+        }
 
         // Plugin Dependencies. Uses `platformBundledPlugins` property from the gradle.properties file for bundled IntelliJ Platform plugins.
         bundledPlugins(providers.gradleProperty("platformBundledPlugins").map { it.split(',') })
 
@@ -4,24 +4,24 @@ pluginName=IntelliJ Protobuf Language Plugin
 pluginRepositoryUrl=https://github.com/devkanro/intellij-protobuf-plugin
 
 # SemVer format -> https://semver.org
-pluginVersion=2.3.0
+pluginVersion=2.4.0
 
 # Supported build number ranges and IntelliJ Platform versions -> https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html
-pluginSinceBuild=253
-pluginUntilBuild=253.*
+pluginSinceBuild=261
+pluginUntilBuild=261.*
 
 # IntelliJ Platform Properties -> https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html#configuration-intellij-extension
 platformType=IU
-platformVersion=2025.3
+platformVersion=2026.1
 
 # Plugin Dependencies -> https://plugins.jetbrains.com/docs/intellij/plugin-dependencies.html
 # Example: platformPlugins = com.jetbrains.php:203.4449.22, org.intellij.scala:2023.3.27@EAP, com.intellij.grpc:251.23774.350
-platformPlugins=org.jetbrains.plugins.go:253.28294.251, com.jetbrains.restClient:253.28294.251
+platformPlugins=org.jetbrains.plugins.go:261.22158.277, com.jetbrains.restClient:261.22158.182
 # Example: platformBundledPlugins = com.intellij.java
 platformBundledPlugins=com.intellij.java, org.jetbrains.kotlin, com.intellij.modules.json, org.intellij.plugins.markdown
 
 # Gradle Releases -> https://github.com/gradle/gradle/releases
-gradleVersion = 8.10.2
+gradleVersion = 9.0.0
 
 # Opt-out flag for bundling Kotlin standard library -> https://jb.gg/intellij-platform-kotlin-stdlib
 kotlin.stdlib.default.dependency = false
 
@@ -4,11 +4,11 @@ junit = "4.13.2"
 
 # plugins
 changelog = "2.2.1"
-intelliJPlatform = "2.5.0"
-kotlin = "2.3.0-RC3"
+intelliJPlatform = "2.16.0"
+kotlin = "2.3.20"
 kover = "0.8.3"
 qodana = "2024.2.3"
-grammarkit = "2023.3"
+grammarkit = "2023.3.0.3"
 
 [libraries]
 junit = { group = "junit", name = "junit", version.ref = "junit" }
 
@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
@@ -0,0 +1,44 @@
+---
+tags: [architecture, extension-points, api]
+related: [architecture/layer-diagram, modules/java, modules/go]
+refs: [docs/extension-points.md]
+---
+# Extension Points
+
+Five extension points allow third-party plugins to extend the core. All are dynamic (support runtime loading/unloading).
+
+## rootProvider
+
+**Interface**: `ProtobufRootProvider`
+
+Provides import root directories for proto file resolution. Built-in: `ModuleSourceRootProvider`, `LibraryRootProvider`, `EmbeddedRootProvider`, `DecompiledRootProvider`, `GoRootProvider`.
+
+```xml
+<extensions defaultExtensionNs="io.kanro.idea.plugin.protobuf">
+    <rootProvider implementation="com.example.MyRootProvider"/>
+</extensions>
+```
+
+## symbolReferenceProvider
+
+**Interface**: `ProtobufSymbolReferenceProvider`
+
+Custom symbol references beyond standard proto references. Used by AIP to resolve resource type names in string literals.
+
+## indexProvider
+
+**Interface**: `ProtobufIndexProvider`
+
+Contributes index entries for proto elements, enabling navigation between proto definitions and generated code. Built-in: `JavaIndexProvider`, `GoIndexProvider`, `SisyphusIndexProvider`.
+
+## stubExternalProvider
+
+**Interface**: `ProtobufStubExternalProvider`
+
+Provides additional external data stored alongside PSI stubs. Used by Java integration to cache Java option values (`java_package`, `java_outer_classname`, `java_multiple_files`).
+
+## protocPlugin
+
+**Interface**: `ProtobufCompilerPlugin`
+
+Hooks into the protobuf compilation process. 10 built-in compilers cover File, Message, Field, Oneof, MapEntry, MapField, Enum, EnumValue, Service, and ServiceMethod compilation.
@@ -0,0 +1,46 @@
+---
+tags: [architecture, overview, layers]
+related: [architecture/extension-points, design/psi-mixin-injection]
+refs: [docs/architecture.md, docs/overview.md]
+---
+# Plugin Architecture Layers
+
+IntelliJ Protobuf Language Plugin is a full-featured Protocol Buffers language plugin for JetBrains IDEs with deep semantic understanding, cross-file symbol resolution, multi-language integration, and Editions support.
+
+## Layer Diagram
+
+```
+┌─────────────────────────────────────────────┐
+│             UI & Settings                   │
+│   Settings, Structure View, Icons, Actions  │
+├─────────────────────────────────────────────┤
+│           Language Support                  │
+│   Completion, Formatting, Annotations,      │
+│   References, Quick Fixes, Find Usages      │
+├─────────────────────────────────────────────┤
+│         PSI (Program Structure)             │
+│   Elements, Mixins, Scope, Features         │
+├─────────────────────────────────────────────┤
+│           Indexing & Stubs                  │
+│   Stub Indices, Root Providers, Caching     │
+├─────────────────────────────────────────────┤
+│           Parsing & Lexing                  │
+│   Lexer (FLEX), Parser (BNF), Language Def  │
+├─────────────────────────────────────────────┤
+│       Integration Modules (Optional)        │
+│   Java, Go, Sisyphus, gRPC, AIP            │
+└─────────────────────────────────────────────┘
+```
+
+Each layer depends only on the layer below it. Integration modules sit alongside, hooking into specific layers via extension points.
+
+## Key Concepts
+
+- **Proto Files as First-Class Code**: `.proto` files get full PSI trees, stub indices, and cross-project reference resolution like Java or Kotlin.
+- **Multi-Source Symbol Resolution**: Root providers aggregate proto files from project sources, library JARs, the protobuf SDK, and decompiled descriptors.
+- **Integration Modules**: Language-specific features activate only when relevant IDE plugins are present, keeping the core lightweight.
+- **Internal Compiler**: In-process protobuf compiler produces `FileDescriptorProto` from PSI without external `protoc`.
+
+## Parsing & Lexing
+
+Grammar files in `src/main/grammar/` define the syntax — `protobuf.bnf` for proto2/proto3/editions, `prototext.bnf` for text format. Grammar-Kit and JFlex generate the parser and lexer. Generated code goes to `build/generated/sources/grammar/`.
@@ -0,0 +1,29 @@
+---
+tags: [design, annotation, validation, proto2, proto3]
+related: [design/annotation-quick-fixes, design/editions-feature-model]
+refs: [docs/design/annotation-system.md]
+---
+# Annotation System — Layered Validation
+
+Protobuf is three divergent dialects sharing one syntax. Proto2 *requires* field labels; proto3 *forbids* `required`. Proto3 bans groups, extensions, default values — all legal in proto2. A single validator would devolve into a tangle of conditionals.
+
+## Per-Version Annotators
+
+| Layer | Class | Activates When |
+|-------|-------|----------------|
+| Universal | `ProtobufAnnotator` | Always (all `.proto` files) |
+| Proto2 | `Protobuf2Annotator` | `syntax` is `"proto2"` or unspecified |
+| Proto3 | `Protobuf3Annotator` | `syntax` is exactly `"proto3"` |
+| Editions | `ProtobufEditionAnnotator` | `edition()` is non-null |
+
+Each version annotator self-gates with an early return. Gating is cheap — a single `file.syntax()` call.
+
+## Annotators Over Inspections
+
+Protobuf errors are specification violations — `protoc` will reject the file. Making them suppressible via inspections would let users silence real errors. Annotators mirror the compiler: always on, not negotiable. Naming convention warnings use `WEAK_WARNING` severity.
+
+## Trackers (Cached Utilities)
+
+`FileTracker`, `NumberTracker`, and `ScopeTracker` use `CachedValuesManager` to compute constraint sets once per PSI modification. Individual `visit()` calls check a single element against the cached set — O(1) lookup, avoiding O(n²) recomputation.
+
+**Record-Visit pattern**: Each tracker records all definitions in a scope during construction, then exposes `visit(element, holder)` methods that check one element against the recorded set.