diff --git a/.github/ISSUE_TEMPLATE/agent_task.yml b/.github/ISSUE_TEMPLATE/agent_task.yml
new file mode 100644
index 00000000..db823c43
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/agent_task.yml
@@ -0,0 +1,38 @@
+name: AI agent task
+description: Small, scoped task suitable for Copilot Coding Agent or another AI agent.
+title: "[Agent]: "
+labels:
+  - agent-ready
+body:
+  - type: textarea
+    id: task
+    attributes:
+      label: Task
+      description: Describe the concrete change or investigation.
+      placeholder: "Example: Add a focused test for Maven proxy 404 negative-cache TTL behavior."
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope boundaries
+      description: List files, modules, or behavior that should not be changed.
+      placeholder: "Keep this to compat-test and server tests; do not change production code unless the test exposes a bug."
+    validations:
+      required: false
+  - type: textarea
+    id: validation
+    attributes:
+      label: Expected validation
+      description: Commands or checks the agent should run.
+      value: |
+        - mvn -pl server -am -Dsurefire.failIfNoSpecifiedTests=false test
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Extra context
+      description: Links, logs, screenshots, or compatibility notes.
+    validations:
+      required: false
diff --git a/.github/agents/docs-syncer.md b/.github/agents/docs-syncer.md
new file mode 100644
index 00000000..a0943380
--- /dev/null
+++ b/.github/agents/docs-syncer.md
@@ -0,0 +1,16 @@
+---
+name: docs-syncer
+description: Keep kkRepo public documentation accurate and bilingual.
+tools: ["read", "edit", "search"]
+---
+
+You maintain kkRepo documentation.
+
+Rules:
+
+- Keep `docs/en` and `docs/zh` aligned for shared feature documentation.
+- Keep claims tied to implemented code, tests, or documented limitations.
+- Use `kkRepo` / `kkrepo` as the product name.
+- Use `Nexus` only as a compatibility or migration reference.
+- Keep root README files concise and move detailed operations into docs.
+- Avoid internal-only deployment details in public-facing text.
diff --git a/.github/agents/protocol-compat-reviewer.md b/.github/agents/protocol-compat-reviewer.md
new file mode 100644
index 00000000..9f29c9a9
--- /dev/null
+++ b/.github/agents/protocol-compat-reviewer.md
@@ -0,0 +1,17 @@
+---
+name: protocol-compat-reviewer
+description: Review protocol changes for Nexus and official client compatibility.
+tools: ["read", "search"]
+---
+
+You review kkRepo protocol changes. Focus on hosted, proxy, and group repository compatibility with Nexus and the official package protocol.
+
+Check:
+
+- HTTP status codes, headers, body shape, redirects, auth challenges, and checksum behavior.
+- Hosted write policy and delete semantics.
+- Proxy cache, negative cache, conditional request, timeout, and retry behavior.
+- Group member ordering and conflict behavior.
+- Compatibility test coverage under `compat-test`.
+
+Call out concrete file and line references. Prefer actionable findings over style comments.
diff --git a/.github/agents/security-reviewer.md b/.github/agents/security-reviewer.md
new file mode 100644
index 00000000..351aea31
--- /dev/null
+++ b/.github/agents/security-reviewer.md
@@ -0,0 +1,17 @@
+---
+name: security-reviewer
+description: Review kkRepo changes for security-sensitive risks.
+tools: ["read", "search"]
+---
+
+You review kkRepo security-sensitive changes.
+
+Focus on:
+
+- Authentication, authorization, user/group/role permissions, CI tokens, API keys, and sessions.
+- Upload, delete, migration, and background worker authorization boundaries.
+- SSRF and outbound request policy for proxy repositories and connectivity checks.
+- Secret handling, encryption keys, token storage, and audit logging.
+- Multi-replica correctness for sessions, auth caches, revocation, and token watermarks.
+
+Report concrete risks first, with file and line references, then suggest targeted tests.
diff --git a/.github/agents/test-writer.md b/.github/agents/test-writer.md
new file mode 100644
index 00000000..86f06b19
--- /dev/null
+++ b/.github/agents/test-writer.md
@@ -0,0 +1,17 @@
+---
+name: test-writer
+description: Add focused tests for kkRepo changes.
+tools: ["read", "edit", "search", "execute"]
+---
+
+You add focused tests for kkRepo changes.
+
+Rules:
+
+- Use the existing test style and helpers.
+- Prefer narrow unit tests for small behavior changes.
+- Add compatibility tests under `compat-test` for protocol behavior changes.
+- For `server` tests, run Maven with `-am` and `-Dsurefire.failIfNoSpecifiedTests=false` when selecting specific tests.
+- Cover concurrency, rollback, duplicate writes, cache invalidation, auth, and permission behavior when touched.
+
+Keep implementation changes minimal unless needed to make the testable behavior correct.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..c4d266be
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,33 @@
+# kkRepo Copilot Instructions
+
+kkRepo is a Nexus-compatible, self-hosted artifact repository. Treat Nexus and the official package protocols as compatibility references. Do not invent protocol behavior from memory.
+
+## Engineering Rules
+
+- Use Java 25.
+- Prefer the existing module boundaries and local helper APIs.
+- Keep server-side protocol logic out of controllers; controllers should delegate to protocol services/adapters.
+- Large blobs belong in OSS/S3-compatible storage. MySQL stores metadata, indexes, references, users, permissions, tokens, audit data, and migration state.
+- Any stateful feature must work in distributed multi-replica deployments. Do not rely on a single JVM as the source of truth for sessions, uploads, deletes, locks, background jobs, cache invalidation, metadata rebuilds, negative cache, or permission decisions.
+- In-process cache is allowed only as rebuildable hot cache with a clear TTL or invalidation path.
+- Migration is a product feature, not a one-off script. Prefer idempotent dry-run, resume, checksum validation, and reporting.
+
+## Build and Test
+
+- When compiling or testing `server`, always use `-am`, for example `mvn -pl server -am test`.
+- When selecting one server test with `-am`, include `-Dsurefire.failIfNoSpecifiedTests=false`.
+- Use Java 25 explicitly if the local shell may not be configured:
+  `JAVA_HOME=/opt/homebrew/Cellar/openjdk@25/25.0.3/libexec/openjdk.jdk/Contents/Home`.
+- Before replacing a runtime jar, build an executable Spring Boot jar with:
+  `mvn -pl server -am -DskipTests package spring-boot:repackage`.
+
+## Compatibility Workflow
+
+- Add or update compatibility tests under `compat-test` for protocol behavior changes.
+- Compare HTTP status, headers, body semantics, generated metadata, checksums, and real client behavior.
+- Normalize host, timestamps, ordering, or generated IDs only when the protocol allows it.
+
+## Review Focus
+
+- Look for Nexus compatibility regressions, multi-replica state bugs, metadata/index consistency issues, unsafe upload/delete behavior, permission bypasses, SSRF risk in proxy repositories, and missing tests.
+- For docs, keep `docs/en` and `docs/zh` aligned when both locales cover the same behavior.
diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md
new file mode 100644
index 00000000..1d8acc89
--- /dev/null
+++ b/.github/instructions/docs.instructions.md
@@ -0,0 +1,12 @@
+---
+applyTo: "README*.md,docs/**/*.md,.github/**/*.md"
+---
+
+# Documentation Instructions
+
+- Keep public wording anchored to implemented behavior.
+- Use `kkRepo` / `kkrepo` as the product name. Use `Nexus` only as a compatibility or migration reference.
+- Keep Chinese docs under `docs/zh` and English docs under `docs/en` aligned when both describe the same feature.
+- Prefer version-precise claims and explicit caveats over broad roadmap wording.
+- For development and deployment docs, include Java 25 and the `server -am` Maven guidance where relevant.
+- Do not include internal deployment details in public-facing docs unless the file is explicitly about local development or deployment.
diff --git a/.github/instructions/frontend.instructions.md b/.github/instructions/frontend.instructions.md
new file mode 100644
index 00000000..3a9c9942
--- /dev/null
+++ b/.github/instructions/frontend.instructions.md
@@ -0,0 +1,12 @@
+---
+applyTo: "admin-ui/**,browse-ui/**"
+---
+
+# Frontend Instructions
+
+- Admin UI should be operational and information-dense. Prioritize repository state, permissions, storage health, migration progress, and audit visibility.
+- Browse UI should be fast, clear, and predictable for artifact discovery and download workflows.
+- Avoid decorative marketing layouts in operational screens.
+- Preserve existing static-resource structure served by Spring Boot.
+- If static assets are changed, run resource processing or a server compile so `target/classes` reflects the change before live verification.
+- Keep text concise and domain-specific. Do not add visible instructions for obvious UI controls.
diff --git a/.github/instructions/java-server.instructions.md b/.github/instructions/java-server.instructions.md
new file mode 100644
index 00000000..0ecb6885
--- /dev/null
+++ b/.github/instructions/java-server.instructions.md
@@ -0,0 +1,14 @@
+---
+applyTo: "server/**,core/**,persistence-mysql/**,cache/**,storage-*/**,migration-nexus/**"
+---
+
+# Java Server Instructions
+
+- Use Java 25 language and library assumptions.
+- Keep transactional metadata in MySQL and blob bytes in the configured blob storage.
+- Use explicit unique constraints and transactions for path, package, version, asset, token, permission, and upload identities.
+- Prefer shared DAO/service abstractions already present in the repository.
+- Do not introduce node-local correctness dependencies. JVM-local state must be a hot cache only and must be reconstructable.
+- For request handling, preserve Nexus-compatible status codes, headers, and response body semantics.
+- Add focused tests for concurrency, duplicate writes, rollback cleanup, permission checks, and cache invalidation when touching shared behavior.
+- Run server checks with `mvn -pl server -am ...`, not `mvn -pl server ...` alone.
diff --git a/.github/instructions/protocol-compat.instructions.md b/.github/instructions/protocol-compat.instructions.md
new file mode 100644
index 00000000..575072f8
--- /dev/null
+++ b/.github/instructions/protocol-compat.instructions.md
@@ -0,0 +1,13 @@
+---
+applyTo: "protocol-*/**,compat-test/**,server/src/main/java/com/github/klboke/kkrepo/server/**/*Service.java,server/src/main/java/com/github/klboke/kkrepo/server/**/*Controller.java"
+---
+
+# Protocol Compatibility Instructions
+
+- Check the official protocol and Nexus behavior before changing hosted, proxy, or group repository behavior.
+- Keep URL layout compatible with `/repository/<repo>/...` unless a protocol-specific endpoint requires another layout.
+- For hosted writes, preserve write policy, checksum, metadata, and error response semantics.
+- For proxy repositories, treat upstream status, headers, cache TTLs, negative cache, conditional requests, and body-read failures carefully.
+- For group repositories, preserve member ordering and deterministic conflict handling.
+- Add or update black-box compatibility tests under `compat-test` when protocol behavior changes.
+- Do not mark protocol work complete until real client behavior or compatibility tests cover the changed path.
diff --git a/.github/prompts/compat-risk-triage.prompt.md b/.github/prompts/compat-risk-triage.prompt.md
new file mode 100644
index 00000000..978415e6
--- /dev/null
+++ b/.github/prompts/compat-risk-triage.prompt.md
@@ -0,0 +1,22 @@
+---
+mode: agent
+description: Summarize compatibility and distributed-state risks in a kkRepo change.
+---
+
+Review this kkRepo change for compatibility and distributed-state risk.
+
+Change summary:
+${input:summary:Paste the change summary here}
+
+Diff excerpt:
+${input:diff:Paste the relevant diff excerpt here}
+
+Focus on:
+
+1. Nexus and official protocol compatibility risks.
+2. Multi-replica state, cache, lock, upload, delete, metadata, and permission correctness.
+3. MySQL metadata consistency and OSS/S3 blob safety.
+4. Missing tests or validation commands.
+5. A concise merge-readiness recommendation.
+
+Use concrete file and line references when available.