[Docs] Mirror lmcache/ layout in docs/design/ for discoverability by ApostaC · Pull Request #3040 · LMCache/LMCache

ApostaC · 2026-04-15T20:49:53Z

What this PR does / why we need it:

Reorganizes docs/design/ to mirror the lmcache/ package tree so developers
and coding agents can easily locate the design doc for a given module:
a module at lmcache/<path>/ has design docs at docs/design/<path>/.

Concretely:

Moved existing design docs into the mirrored paths (e.g.,
docs/design/l2_adapters/ → docs/design/v1/distributed/l2_adapters/,
docs/design/cli/describe.md → docs/design/cli/commands/describe.md).
Moved design-flavored .md files from inside lmcache/ into the
corresponding docs/design/<path>/ location (DESIGN.md, EVENTS.md,
METRICS.md from lmcache/v1/mp_observability/).
Kept user-entry-point README.md files co-located with code; added
relative symlinks from the mirrored docs/design/<path>/README.md so the
mirror tree is complete.
Added docs/design/README.md explaining the convention.
Updated CLAUDE.md, AGENTS.md, docs/coding_standards.md §5.1, and
.claude/skills/pr-review/SKILL.md so both humans and coding agents are
directed to the mirrored location when looking for or adding design docs.
Fixed relative links inside moved docs.

Special notes for your reviewers:

This branch is forked off chore/coding-standard (PR #3039). Please rebase
this PR onto dev after #3039 is merged so the PR shows only the docs-layout
changes.

If applicable:

this PR contains user facing changes - docs added
this PR contains unit tests

Note

Low Risk
Docs-only reorganization plus link/reference updates; primary risk is broken doc links or tooling that assumes the old docs/design/ paths.

Overview
Standardizes design documentation by making docs/design/ mirror the lmcache/ package tree, so design docs for lmcache/<path>/ live under docs/design/<path>/.

Adds docs/design/README.md to document the convention, drops in mirrored README.md link stubs for select modules, and fixes internal relative links in moved design docs (e.g., CLI command docs and L2 adapter docs). Updates agent and contributor guidance (AGENTS.md, CLAUDE.md, .claude/skills/pr-review/SKILL.md, docs/coding_standards.md) plus MP observability references (lmcache/v1/mp_observability/*, event.py) to point at the new docs/design/v1/mp_observability/ locations.

^{Reviewed by Cursor Bugbot for commit 65292f7. Bugbot is set up for automated code reviews on this repo. Configure here.}

gemini-code-assist

Code Review

This pull request establishes a comprehensive code quality and review standard for the LMCache project, including the addition of docs/coding_standards.md, a new CLAUDE.md guide, and specialized review/check skills for AI agents. It also reorganizes design documentation to mirror the lmcache/ package structure and updates various READMEs and source files to point to these new locations. The review feedback identifies several opportunities to improve path consistency for automated agents and highlights a minor naming inconsistency with the newly established documentation guidelines.

gemini-code-assist · 2026-04-15T20:57:34Z


 When working in `lmcache/v1/mp_observability/`:

+Design docs live in `docs/design/v1/mp_observability/` — update them whenever


For consistency with the relative links in README.md and to ensure coding agents can correctly resolve the path from this directory, please use the relative path from the repository root by adding the ../../../ prefix.

Suggested change

Design docs live in `docs/design/v1/mp_observability/` — update them whenever

Design docs live in ../../../docs/design/v1/mp_observability/ — update them whenever

gemini-code-assist · 2026-04-15T20:57:34Z

+   metadata contract table in `docs/design/v1/mp_observability/EVENTS.md`
+   with the new type's metadata keys and types.


The path to EVENTS.md should be relative to this file's location to ensure it is discoverable by agents working within this module, consistent with the pattern used in README.md.

Suggested change

metadata contract table in `docs/design/v1/mp_observability/EVENTS.md`

with the new type's metadata keys and types.

metadata contract table in ../../../docs/design/v1/mp_observability/EVENTS.md\

with the new type's metadata keys and types.

gemini-code-assist · 2026-04-15T20:57:34Z


 2. **New metrics subscriber** — after adding counters/histograms, update the
-   metrics table in `METRICS.md` with the metric name, type, and description.
+   metrics table in `docs/design/v1/mp_observability/METRICS.md` with the


Please update this path to be relative to the current directory for consistency and better discoverability by automated agents.

Suggested change

metrics table in `docs/design/v1/mp_observability/METRICS.md` with the

metrics table in ../../../docs/design/v1/mp_observability/METRICS.md with the

gemini-code-assist · 2026-04-15T20:57:34Z

-   ("How to Add a New Event and Subscriber") and the design rules in
-   `DESIGN.md`.
+   (co-located with this file; "How to Add a New Event and Subscriber") and
+   the design rules in `docs/design/v1/mp_observability/DESIGN.md`.


Please update this path to be relative to the current directory.

Suggested change

the design rules in `docs/design/v1/mp_observability/DESIGN.md`.

the design rules in ../../../docs/design/v1/mp_observability/DESIGN.md.

gemini-code-assist · 2026-04-15T20:57:34Z

        metadata: Flat key-value payload.  Contents depend on ``event_type``;
-            see the metadata contracts in DESIGN.md Section 2.7.
+            see the metadata contracts in
+            ``docs/design/v1/mp_observability/DESIGN.md`` Section 2.7.


To maintain consistency with the relative paths established in the module's README.md and to assist coding agents in locating the design documentation from this source file, consider using a relative path from the repository root.

Suggested change

``docs/design/v1/mp_observability/DESIGN.md`` Section 2.7.

../../../docs/design/v1/mp_observability/DESIGN.md Section 2.7.

gemini-code-assist · 2026-04-15T20:57:34Z

+- Use descriptive file names (e.g., `overall.md`, `l2_eviction.md`, `query-command.md`)
+  rather than mirroring module file names. See `docs/design/README.md` for the full
+  convention.


The newly established standard in this file (and in docs/design/README.md) recommends using descriptive file names rather than mirroring module file names. However, describe.md and ping.md in docs/design/cli/commands/ still mirror their respective module names (describe.py and ping.py). Consider renaming them to something more descriptive, such as describe-command.md and ping-command.md, to adhere to this guideline.

Signed-off-by: ApostaC <yihua98@uchicago.edu>

royyhuang

Btw do we have design docs for the core components in mp mode, for example, our listeners and controllers pattern? It would great if we can add those!

royyhuang · 2026-04-16T00:04:41Z

Probably rename this to event-bus.md following other design docs naming convention. Similarly for other files in this dir.

sammshen

LGTM

ApostaC · 2026-04-16T01:03:00Z

Btw do we have design docs for the core components in mp mode, for example, our listeners and controllers pattern? It would great if we can add those!

@royyhuang I double-checked, and there are no extra design docs in lmcache. The only docs left there are readme (which is supposed to be read by humans). I have also created symbolic links of those readme files into docs/design.

Signed-off-by: ApostaC <yihua98@uchicago.edu>

ApostaC requested review from deng451e and sammshen as code owners April 15, 2026 20:49

gemini-code-assist Bot reviewed Apr 15, 2026

View reviewed changes

ApostaC added 3 commits April 15, 2026 23:44

moving the docs to docs/design/ and reorganize the docs/design folder

e980c85

Signed-off-by: ApostaC <yihua98@uchicago.edu>

move other design docs

66482c9

Signed-off-by: ApostaC <yihua98@uchicago.edu>

[Add] instructions for new doc layout

fd53215

Signed-off-by: ApostaC <yihua98@uchicago.edu>

ApostaC force-pushed the claude/vibrant-vaughan branch from bca5cb1 to fd53215 Compare April 15, 2026 23:44

royyhuang reviewed Apr 16, 2026

View reviewed changes

sammshen approved these changes Apr 16, 2026

View reviewed changes

update

0802b13

Signed-off-by: ApostaC <yihua98@uchicago.edu>

ApostaC mentioned this pull request Apr 16, 2026

[MP][Feat] Add cache_salt to ObjectKey for cache isolation #3042

Merged

4 tasks

Oasis-Git approved these changes Apr 16, 2026

View reviewed changes

ApostaC enabled auto-merge (squash) April 16, 2026 15:48

github-actions Bot added the full Run comprehensive tests on this PR label Apr 16, 2026

ApostaC added 2 commits April 16, 2026 15:49

Merge branch 'dev' into claude/vibrant-vaughan

a4592a8

Merge branch 'dev' into claude/vibrant-vaughan

65292f7

ApostaC merged commit 9b3f27b into LMCache:dev Apr 16, 2026
36 of 38 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Mirror lmcache/ layout in docs/design/ for discoverability#3040

[Docs] Mirror lmcache/ layout in docs/design/ for discoverability#3040
ApostaC merged 6 commits intoLMCache:devfrom
ApostaC:claude/vibrant-vaughan

ApostaC commented Apr 15, 2026 •

edited by cursor Bot

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

royyhuang left a comment

Uh oh!

royyhuang Apr 16, 2026

Uh oh!

ApostaC Apr 16, 2026

Uh oh!

sammshen left a comment

Uh oh!

ApostaC commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		When working in `lmcache/v1/mp_observability/`:

		Design docs live in `docs/design/v1/mp_observability/` — update them whenever

	Design docs live in `docs/design/v1/mp_observability/` — update them whenever
	Design docs live in ../../../docs/design/v1/mp_observability/ — update them whenever

		metadata contract table in `docs/design/v1/mp_observability/EVENTS.md`
		with the new type's metadata keys and types.

	metrics table in `docs/design/v1/mp_observability/METRICS.md` with the
	metrics table in ../../../docs/design/v1/mp_observability/METRICS.md with the

	the design rules in `docs/design/v1/mp_observability/DESIGN.md`.
	the design rules in ../../../docs/design/v1/mp_observability/DESIGN.md.

	``docs/design/v1/mp_observability/DESIGN.md`` Section 2.7.
	../../../docs/design/v1/mp_observability/DESIGN.md Section 2.7.

Conversation

ApostaC commented Apr 15, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

royyhuang left a comment

Choose a reason for hiding this comment

Uh oh!

royyhuang Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

ApostaC Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

sammshen left a comment

Choose a reason for hiding this comment

Uh oh!

ApostaC commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ApostaC commented Apr 15, 2026 •

edited by cursor Bot

Loading