docs: concepts pages (D2): https://github.com/riboseinc/claude-memory-files/issues/1 - #14
Merged
Conversation
Implements ticket #1 (#1); docs PR D2 of the delivery sequence (after PR 4). Lands the docs/concepts/ section with the five conceptual pages that explain the design decisions behind the v1 schema and category layout: - index.adoc: section landing with cross-links. - scope-rubric.adoc: when to use universal / team / personal-share, with worked seed examples and a Mermaid decision tree. - mechanism-and-data.adoc: the requires-companion pattern, explained via the github-narrative-location ↔ user-maintained-gems pair (and its second consumer, github-pr-assignment). - instructions-vs-memory.adoc: the operational distinction — instructions @-include into CLAUDE.md and load every session; memory files are reference, on-demand. Includes a token-cost discipline note. - settings-fragments.adoc: deep-merge semantics, hand-curated entry preservation, the manifest-recorded merged-fragment that powers clean uninstall + update. - hooks-deferred.adoc: the CVE-2025-59536/CVE-2026-21852 history that motivates the v2 deferral, the v2 policy summary, and the gate condition for opening hooks/. Verified locally: bundle exec jekyll build produces _site/concepts/ with all 6 HTML pages. Sass darken() deprecation warnings are the same Just-the-Docs 0.7.0 noise as canon's site; build exits 0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The existing docs.yml workflow only built + deployed on push to main, so a broken .adoc or invalid frontmatter could only fail at deploy time — after merge. Adds a validate-docs job that runs on pull_request events and runs 'jekyll build --strict_front_matter' to confirm the site compiles. The build and deploy jobs stay gated on non-PR events. Closes the CI gap that PR 14 (and every future docs PR) would otherwise leave: docs PRs now get the same kind of build-on-PR gate that content PRs get from validate.yml's validator + smoke tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements ticket #1; docs PR D2 of the delivery sequence (after PR 4 long since merged).
Lands the
docs/concepts/section — five conceptual pages explaining the design decisions behind the v1 schema and category layout:index.adoc— section landing.scope-rubric.adoc— when to useuniversal/team/personal-share, with worked seed examples and a Mermaid decision tree.mechanism-and-data.adoc— therequires-companionpattern, explained viagithub-narrative-location↔user-maintained-gems(and its second consumer,github-pr-assignment).instructions-vs-memory.adoc— the operational distinction; instructions@-include intoCLAUDE.mdand load every session, memory files are reference. Includes a token-cost discipline note.settings-fragments.adoc— deep-merge semantics, hand-curated entry preservation, the manifest-recordedmerged-fragmentthat powers clean uninstall + update.hooks-deferred.adoc— the CVE-2025-59536 / CVE-2026-21852 history motivating the v2 deferral; v2 policy summary; gate condition for openinghooks/.Verified locally with
bundle exec jekyll build—_site/concepts/renders all six HTML pages. Sassdarken()deprecation warnings are the same Just-the-Docs 0.7.0 noise ascanon's site; build exits 0.D3 (task guides + reference pages + roadmap) is the final remaining v1 PR.
🤖 Generated with Claude Code