v2.2.0: Layer authoritative upstream docs + RCmerci skill cross-refs

Adds Layer 1 (seven files mirrored verbatim from logseq/logseq libs/development-notes/ into skill/references/logseq-official/, refreshed via scripts/sync-logseq-docs.sh) so Claude reaches official API ground truth directly. SKILL.md reorganized into three layers with explicit precedence: Layer 1 wins on API facts; Layer 2 (preserved production patterns from logseq-checklist v1.0.0) wins on real-world pitfalls; Layer 3 points at sibling skills including RCmerci's logseq-schema and logseq-electron-debug. Mixed-license repo: MIT for skill content, AGPL-3.0 for the mirrored subfolder (full license text committed, README notes the boundary). CLAUDE.md File Structure and Rule #1 updated to reflect new scripts/ and gitignored upstream/ at repo root.

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

Author: kerim

.gitignore

@@ -11,3 +11,6 @@
 # Temp files
 *.tmp
 *.bak
+
+# Local mirror of upstream Logseq repo (populated by scripts/sync-logseq-docs.sh)
+upstream/logseq-repo/

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2.2.0] - 2026-04-16
+
+### Added
+
+- **Layer 1: Authoritative upstream docs** — seven files mirrored verbatim from [logseq/logseq `libs/development-notes/`](https://github.com/logseq/logseq/tree/master/libs/development-notes) into `skill/references/logseq-official/`:
+  - `AGENTS.md` — AI-agent development guide (SDK repo structure, conventions)
+  - `starter_guide.md` — plugin bootstrap (Node, TypeScript, hello world)
+  - `db_properties_skill.md` — DB properties SDK reference
+  - `db_properties_guide.md` — File graph vs DB graph property storage
+  - `db_query_guide.md` — Datascript query reference (`logseq.DB.q`, `datascriptQuery`, parameterized Datalog)
+  - `db_tag_property_idents_notes.md` — Ident system and namespace conventions
+  - `experiments_api_guide.md` — `logseq.Experiments` API (React integration, custom renderers)
+- **`scripts/sync-logseq-docs.sh`** — refreshes mirrored docs from upstream via shallow+sparse `git clone`. Idempotent (SHA-based), atomic writes, fails loudly on upstream path renames.
+- **`upstream/logseq-repo/`** — gitignored local mirror, populated by the sync script.
+- **SKILL.md layered structure** with explicit precedence note: Layer 1 (upstream ground truth) → Layer 2 (production patterns) → Layer 3 (related skills). Layer 1 wins on API facts; Layer 2 wins on real-world pitfalls.
+- **Layer 3 cross-references** to RCmerci's skills (`logseq-schema` for Datascript schema, `logseq-electron-debug` for Chrome DevTools against Logseq), plus existing `logseq-db-knowledge` and `logseq-cli-skill`.
+- **Cross-links** added to the five supplementary reference files (`core-apis.md`, `queries-and-database.md`, `event-handling.md`, `property-management.md`, `plugin-architecture.md`) pointing at their corresponding Layer 1 file (or noting "supplementary — no Layer 1 equivalent").
+
+### Changed
+
+- **CLAUDE.md** (repo root) — File Structure diagram now includes `scripts/` and gitignored `upstream/`; Important Rule #1 refined from "only edit files in skill/" to "skill content lives in `skill/` only; repo-maintenance files may be added or modified at repo root" (reflects pre-existing practice with README/CHANGELOG/LICENSE/.gitignore).
+- **README.md** — new "Mirrored upstream docs" section and explicit license boundary between MIT (skill content) and AGPL-3.0 (mirrored subfolder).
+
+### Preserved
+
+- **`references/tag-detection.md`** and **`references/pitfalls-and-solutions.md`** — unchanged; unique production-tested contributions not covered in Layer 1.
+
+### License
+
+- Repo root remains **MIT**.
+- `skill/references/logseq-official/` is **AGPL-3.0** (full license text in that subfolder's `LICENSE`, attribution in its `README.md`). Redistribution of modifications to mirrored content must comply with AGPL-3.0.
+
 ## [2.1.0] - 2025-12-18
 
 ### Added

CLAUDE.md

@@ -7,7 +7,7 @@ This project follows the standardized skill workflow. The skill files are in the
 
 ### Important Rules
 
-1. **Only edit files in the `skill/` folder** - Never edit `~/.claude/skills/` directly (it's a symlink to this folder)
+1. **Skill content lives in `skill/` only** — the `skill/` folder is symlinked to `~/.claude/skills/logseq-db-plugin-api-skill/`. Never edit the symlink target directly; always edit through `skill/` in this repo. Repo-maintenance files (`scripts/`, `upstream/`, `CHANGELOG.md`, `README.md`, `LICENSE`, `.gitignore`) may be added or modified at repo root.
 2. **Update README.md** if functionality changes
 3. **Ask user to review changes** before committing
 4. **Commit and push** after user approval (if remote exists)
@@ -19,22 +19,31 @@ logseq-db-plugin-api-skill/
 ├── skill/                    # Symlinked to ~/.claude/skills/logseq-db-plugin-api-skill/
 │   ├── SKILL.md              # The actual skill definition
 │   └── references/           # Modular detailed documentation
+│       ├── logseq-official/  # Mirrored upstream docs from logseq/logseq (AGPL-3.0)
+│       │   ├── AGENTS.md, starter_guide.md, db_*.md, experiments_api_guide.md
+│       │   ├── LICENSE       # Full AGPL-3.0 text
+│       │   ├── README.md     # Attribution + license boundary
+│       │   └── .last-synced-sha
 │       ├── core-apis.md
 │       ├── event-handling.md
 │       ├── plugin-architecture.md
 │       ├── property-management.md
 │       ├── queries-and-database.md
 │       ├── tag-detection.md
 │       └── pitfalls-and-solutions.md
+├── scripts/                  # Repo-maintenance scripts
+│   └── sync-logseq-docs.sh   # Refreshes skill/references/logseq-official/
+├── upstream/                 # Gitignored — local mirror of logseq/logseq
+│   └── logseq-repo/          # Shallow+sparse clone, populated by sync script
 ├── README.md                 # GitHub install instructions
 ├── CLAUDE.md                 # This file - workflow instructions
 ├── CHANGELOG.md              # Version history
-└── LICENSE                   # MIT License
+└── LICENSE                   # MIT License (covers all content except skill/references/logseq-official/)
 ```
 
 ### Before Committing
 
-- [ ] Changes are in `skill/` folder only
+- [ ] Skill content changes are in `skill/` only; repo-maintenance changes (scripts/, upstream/, CHANGELOG, README) are allowed at root
 - [ ] README.md updated if needed
 - [ ] User has reviewed changes
 - [ ] Version number updated (if applicable)

README.md

@@ -1,16 +1,61 @@
 # Logseq DB Plugin API Skill
 
-**Version**: 2.1.0
-**Updated**: 2025-12-18
+**Version**: 2.2.0
+**Updated**: 2026-04-16
 
-A comprehensive Claude Code skill for developing Logseq plugins specifically for **DB (database) graphs**, now with modular documentation and production-tested patterns.
+A comprehensive Claude Code skill for developing Logseq plugins specifically for **DB (database) graphs**, now with authoritative upstream docs mirrored from logseq/logseq, modular documentation, and production-tested patterns.
 
 ## Overview
 
 This skill provides essential knowledge for building Logseq plugins that work with the new DB graph architecture. It covers the complete plugin API verified against LSPlugin.ts TypeScript definitions, including tag/class management (with **CORRECTED method names**), property handling (with **complete upsertProperty signature**), icon management, tag inheritance, comprehensive type definitions, and proper Vite bundling setup.
 
 **Target Audience**: Developers building plugins for Logseq DB graphs using Claude Code.
 
+## What's New in v2.2.0
+
+### Authoritative Upstream Docs + Related Skills 📚
+
+This release layers the Logseq core team's own agent-oriented documentation on top of the existing production patterns, and points to two related skills from Logseq core dev RCmerci.
+
+**New Layer 1 (authoritative upstream)**: Seven files mirrored verbatim from [logseq/logseq `libs/development-notes/`](https://github.com/logseq/logseq/tree/master/libs/development-notes), refreshed via `scripts/sync-logseq-docs.sh`:
+
+- `AGENTS.md`, `starter_guide.md`, `db_properties_skill.md`, `db_properties_guide.md`, `db_query_guide.md`, `db_tag_property_idents_notes.md`, `experiments_api_guide.md`
+
+These live in `skill/references/logseq-official/` and are licensed **AGPL-3.0** (see License boundary below).
+
+**New Layer 3 (related skills)**: cross-references to [RCmerci's skills](https://github.com/RCmerci/skills):
+
+- `logseq-schema` — authoritative Datascript schema for Datalog queries
+- `logseq-electron-debug` — Chrome DevTools against running Logseq
+
+Install separately from RCmerci's repo; SKILL.md points at them for discoverability.
+
+**SKILL.md reorganized** into 3 layers with explicit precedence: Layer 1 wins on API facts, Layer 2 (existing production patterns) wins on real-world pitfalls.
+
+**No existing content removed.** All v2.1.0 references preserved and back-linked.
+
+## Mirrored Upstream Docs
+
+### What's mirrored
+
+Files under `skill/references/logseq-official/` are copied verbatim from [logseq/logseq](https://github.com/logseq/logseq) master branch via a shallow + sparse git clone at `upstream/logseq-repo/` (gitignored).
+
+Refresh command (from repo root):
+
+```bash
+bash scripts/sync-logseq-docs.sh
+```
+
+The script is idempotent — if upstream HEAD matches the recorded `.last-synced-sha`, it exits without rewriting. Each mirrored file carries a 3-line HTML-comment footer recording the upstream commit SHA and fetch timestamp.
+
+### License boundary
+
+- The root `LICENSE` file is **MIT** and covers the skill's own original content (SKILL.md, most of `skill/references/`, scripts, docs).
+- The subfolder `skill/references/logseq-official/` is **AGPL-3.0**. Its own `LICENSE` file (full AGPL-3.0 text) and `README.md` (attribution + source URLs) make the boundary explicit.
+- **If you redistribute modifications** to files in `skill/references/logseq-official/`, the AGPL-3.0 copyleft applies. The MIT license at repo root does **not** extend into that subfolder.
+
+See [`skill/references/logseq-official/README.md`](./skill/references/logseq-official/README.md) for full attribution and [`skill/references/logseq-official/LICENSE`](./skill/references/logseq-official/LICENSE) for the AGPL-3.0 text.
+
 ## What's New in v2.1.0
 
 ### Advanced Query Patterns 🔍
@@ -522,7 +567,12 @@ Contributions are welcome! If you discover new API features, better patterns, or
 
 ## License
 
-MIT License - feel free to use, modify, and distribute.
+**Mixed-license repository**:
+
+- **MIT License** covers the skill's original content (root `LICENSE`): `SKILL.md`, most of `skill/references/`, `scripts/`, root documentation.
+- **AGPL-3.0** covers mirrored upstream content under `skill/references/logseq-official/` (see `skill/references/logseq-official/LICENSE`). These files are reproduced verbatim from [logseq/logseq](https://github.com/logseq/logseq) with attribution footers.
+
+Redistributing modifications to files under `skill/references/logseq-official/` requires AGPL-3.0 compliance. All other content is MIT — feel free to use, modify, and distribute.
 
 ## Support
 

scripts/sync-logseq-docs.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+#
+# sync-logseq-docs.sh — Mirror logseq/logseq libs/development-notes/ into
+# skill/references/logseq-official/ via shallow+sparse git clone.
+#
+# Usage (from repo root):
+#   bash scripts/sync-logseq-docs.sh
+#
+# Idempotent: if upstream HEAD matches .last-synced-sha, exits 0 without rewriting.
+# Atomic: all copies use .tmp files and are moved into place only after every file succeeds.
+# Trap cleans up .tmp files on any error.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+UPSTREAM_DIR="upstream/logseq-repo"
+UPSTREAM_URL="https://github.com/logseq/logseq.git"
+UPSTREAM_PATH="libs/development-notes"
+TARGET_DIR="skill/references/logseq-official"
+SHA_FILE="$TARGET_DIR/.last-synced-sha"
+
+EXPECTED_FILES=(
+    "AGENTS.md"
+    "starter_guide.md"
+    "db_properties_skill.md"
+    "db_properties_guide.md"
+    "db_query_guide.md"
+    "db_tag_property_idents_notes.md"
+    "experiments_api_guide.md"
+)
+
+trap 'rm -f "$TARGET_DIR"/*.tmp 2>/dev/null || true' EXIT
+
+mkdir -p "$TARGET_DIR"
+
+if [[ ! -d "$UPSTREAM_DIR/.git" ]]; then
+    echo "==> First run: shallow+sparse clone of $UPSTREAM_URL"
+    mkdir -p upstream
+    git clone --depth 1 --filter=blob:none --no-checkout "$UPSTREAM_URL" "$UPSTREAM_DIR"
+    git -C "$UPSTREAM_DIR" sparse-checkout init --cone
+    git -C "$UPSTREAM_DIR" sparse-checkout set "$UPSTREAM_PATH"
+    git -C "$UPSTREAM_DIR" checkout
+else
+    echo "==> Refreshing $UPSTREAM_DIR"
+    git -C "$UPSTREAM_DIR" pull --ff-only
+fi
+
+UPSTREAM_SHA="$(git -C "$UPSTREAM_DIR" rev-parse HEAD)"
+
+if [[ -f "$SHA_FILE" ]] && [[ "$(cat "$SHA_FILE")" == "$UPSTREAM_SHA" ]]; then
+    echo "==> Already up to date at $UPSTREAM_SHA"
+    exit 0
+fi
+
+echo "==> Verifying all $([[ ${#EXPECTED_FILES[@]} -gt 0 ]] && echo ${#EXPECTED_FILES[@]}) expected files exist upstream"
+for f in "${EXPECTED_FILES[@]}"; do
+    if [[ ! -f "$UPSTREAM_DIR/$UPSTREAM_PATH/$f" ]]; then
+        echo "ERROR: expected file missing upstream: $UPSTREAM_PATH/$f" >&2
+        echo "ERROR: upstream may have been reorganized; inspect $UPSTREAM_DIR/$UPSTREAM_PATH/" >&2
+        exit 1
+    fi
+done
+
+FETCHED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "==> Copying files (SHA=$UPSTREAM_SHA, fetched=$FETCHED_AT)"
+
+for f in "${EXPECTED_FILES[@]}"; do
+    SRC="$UPSTREAM_DIR/$UPSTREAM_PATH/$f"
+    TMP="$TARGET_DIR/$f.tmp"
+    DST="$TARGET_DIR/$f"
+    cp "$SRC" "$TMP"
+    # Normalize: some upstream files lack a trailing newline. Add one if missing,
+    # so the footer append doesn't corrupt the final content line. This normalization
+    # is deliberate and documented in skill/references/logseq-official/README.md.
+    if [[ -n "$(tail -c 1 "$TMP")" ]]; then
+        printf '\n' >> "$TMP"
+    fi
+    # Append 3-line footer: blank line + 2 HTML comments
+    printf '\n<!-- logseq-mirror: commit=%s fetched=%s -->\n<!-- logseq-mirror: upstream=https://github.com/logseq/logseq/blob/%s/%s/%s -->\n' \
+        "$UPSTREAM_SHA" "$FETCHED_AT" "$UPSTREAM_SHA" "$UPSTREAM_PATH" "$f" >> "$TMP"
+    mv "$TMP" "$DST"
+done
+
+echo "==> Extracting upstream LICENSE.md (AGPL-3.0) via git show"
+# LICENSE.md at repo root is not in sparse-checkout; read from git object store instead
+# (Named LICENSE.md in logseq/logseq; we save it as LICENSE for clarity in this subfolder)
+git -C "$UPSTREAM_DIR" show HEAD:LICENSE.md > "$TARGET_DIR/LICENSE"
+
+echo "$UPSTREAM_SHA" > "$SHA_FILE"
+
+echo "==> Synced ${#EXPECTED_FILES[@]} files + LICENSE at SHA $UPSTREAM_SHA"