Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ Every entry states what was actually tested. A static check or an authored examp
is not a behavioral evaluation, and adopting a version is an implementation choice,
not a demonstrated accuracy gain.

The latest bundle is described in the [v0.2.7 release notes](docs/releases/v0.2.7.md).
The latest bundle is described in the [v0.2.8 release notes](docs/releases/v0.2.8.md).
Previous [v0.2.7 release notes](docs/releases/v0.2.7.md) are retained.
Previous [v0.2.6 release notes](docs/releases/v0.2.6.md) are retained.
Previous [v0.2.5 release notes](docs/releases/v0.2.5.md) are retained.
Previous [v0.2.4 release notes](docs/releases/v0.2.4.md) are retained.
Expand All @@ -24,7 +25,7 @@ Earlier [v0.1.6 release notes](docs/releases/v0.1.6.md) are retained.
Earlier contents and validation are summarized in the [v0.1.5 release notes](docs/releases/v0.1.5.md),
with earlier [v0.1.4](docs/releases/v0.1.4.md) and [v0.1.3](docs/releases/v0.1.3.md) notes retained.

## context-docs 0.2.8 — 2026-11-21 (unreleased)
## context-docs 0.2.8 — 2026-11-22

- Specify how Codex and Claude Code hand off edits to a shared context file
through the task channel or the user. Keep private context and journal
Expand All @@ -33,8 +34,8 @@ with earlier [v0.1.4](docs/releases/v0.1.4.md) and [v0.1.3](docs/releases/v0.1.3
private scratch path for a file-backed payload.
- Checked with repository static, journal and site tests on Python 3.9 and
3.14. An isolated install verified both packages in Codex and Claude Code
project layouts. See the [candidate notes](docs/releases/v0.2.8.md#candidate-checks)
for the scope and remaining publication steps.
project layouts. See the [release notes](docs/releases/v0.2.8.md#candidate-checks)
for the scope of those checks.

## Experimental Antigravity support label — 2026-11-17 (no package release)

Expand Down
25 changes: 13 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,11 @@ next session to read them.

[Website](https://context-docs.com/) · [Get started](#get-started) · [See an example](#what-you-get) · [User guide](docs/getting-started.md) · [Evidence](docs/evaluation-results.md) · [Contribute](CONTRIBUTING.md)

**Status: experimental, core skill v0.2.8 (unreleased) and adoption skill v0.1.16.**
The published bundle remains v0.2.7.
**Status: experimental, core skill v0.2.8 and adoption skill v0.1.16.**
The [v0.2.8 experimental prerelease](docs/releases/v0.2.8.md) covers shared
writer handoff and private journal input. Everyday installation selects this bundle.
The [v0.2.7 release notes](docs/releases/v0.2.7.md) cover a narrow instruction
simplification and qualified checks. Everyday installation selects this bundle.
simplification and qualified checks.
The Codex candidate report's automatic-loading confirmation remains unverified;
Claude instruction events support loading in its checked sessions only.
The [v0.2.6 release notes](docs/releases/v0.2.6.md) cover metadata filtering,
Expand Down Expand Up @@ -74,7 +75,7 @@ cases show how to hand off the same project through saved Markdown.

Install both skills, then adopt them in the project you want to maintain.
Already installed? Skip to [Use it](#use-it).
The instructions below select published bundle **v0.2.7**: core **0.2.7** and
The instructions below select published bundle **v0.2.8**: core **0.2.8** and
adoption **0.1.16**. See the [guide](docs/getting-started.md#development-source-installs)
for development-source installations.

Expand All @@ -84,13 +85,13 @@ Ask Codex:

```text
Use $skill-installer to install both skills from jaredchu/context-docs
at the published tag v0.2.7:
at the published tag v0.2.8:
- skills/context-docs
- skills/adopt-context-docs
Install them together in ~/.agents/skills/.
Preserve existing installations and local customizations; report version
mismatches before upgrading. Report the installed VERSION values:
context-docs 0.2.7 and adopt-context-docs 0.1.16.
context-docs 0.2.8 and adopt-context-docs 0.1.16.
```

[Manual installation and project-only setup →](docs/getting-started.md#install-in-codex)
Expand All @@ -100,7 +101,7 @@ context-docs 0.2.7 and adopt-context-docs 0.1.16.
For a first installation, run these commands in a terminal:

```sh
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git
cd context-docs
mkdir -p ~/.claude/skills
cp -r skills/context-docs skills/adopt-context-docs ~/.claude/skills/
Expand All @@ -109,7 +110,7 @@ cat ~/.claude/skills/context-docs/VERSION ~/.claude/skills/adopt-context-docs/VE

If either skill is already installed, [review the upgrade guidance](docs/getting-started.md#upgrading)
before copying files. [Project-only setup and instruction loading →](docs/getting-started.md#install-in-claude-code)
The version output should be `0.2.7` followed by `0.1.16`.
The version output should be `0.2.8` followed by `0.1.16`.

<a id="install-in-cursor-cli-experimental"></a>
### Install in Cursor (experimental)
Expand All @@ -125,7 +126,7 @@ in Cursor's own user directory (**fresh placement not tested**):

```sh
(
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git &&
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git &&
cd context-docs &&
mkdir -p ~/.cursor/skills &&
test ! -e ~/.cursor/skills/context-docs &&
Expand All @@ -136,7 +137,7 @@ in Cursor's own user directory (**fresh placement not tested**):
```

The sequence stops at the first failure: a failed clone copies nothing, and the
guard copies nothing if either folder already exists. Expect `0.2.7` then
guard copies nothing if either folder already exists. Expect `0.2.8` then
`0.1.16`; no version output means installation did not complete. [Cursor setup, evidence and limits →](docs/getting-started.md#cursor-experimental)

<a id="install-in-antigravity-provisional"></a>
Expand All @@ -158,15 +159,15 @@ From the root of your target project, for a first installation:
test ! -L .agents/skills/context-docs &&
test ! -e .agents/skills/adopt-context-docs &&
test ! -L .agents/skills/adopt-context-docs &&
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git context-docs-skills &&
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git context-docs-skills &&
mkdir -p .agents/skills &&
cp -r context-docs-skills/skills/context-docs context-docs-skills/skills/adopt-context-docs .agents/skills/ &&
cat .agents/skills/context-docs/VERSION .agents/skills/adopt-context-docs/VERSION
)
```

The guards preserve existing folders and symlinks; a failed clone copies nothing.
The source checkout is `context-docs-skills/` in your project. Expect `0.2.7` then
The source checkout is `context-docs-skills/` in your project. Expect `0.2.8` then
`0.1.16`. Reuse existing project copies; review the upgrade guidance before
replacing them. [Antigravity setup, evidence and limits →](docs/getting-started.md#antigravity-experimental)

Expand Down
31 changes: 15 additions & 16 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

Install both skills once, adopt them in a project, and let its maintenance rule keep
context current after meaningful work. No background service is installed.
Everyday installation below selects published bundle **v0.2.7**:
core **0.2.7** and adoption **0.1.16**. The [release notes](releases/v0.2.7.md)
Everyday installation below selects published bundle **v0.2.8**:
core **0.2.8** and adoption **0.1.16**. The [release notes](releases/v0.2.8.md)
retain the bundle scope and evidence limits.

## Install in Codex
Expand All @@ -14,23 +14,23 @@ Ask the built-in installer:

```text
Use $skill-installer to install both skills from jaredchu/context-docs
at the published tag v0.2.7:
at the published tag v0.2.8:
- skills/context-docs
- skills/adopt-context-docs
Install them together in ~/.agents/skills/.
Preserve existing installations and local customizations; report version
mismatches before upgrading. Report the installed VERSION values:
context-docs 0.2.7 and adopt-context-docs 0.1.16.
context-docs 0.2.8 and adopt-context-docs 0.1.16.
```

The adoption skill requires `context-docs` as a sibling folder. It is a small
setup wrapper, not a standalone replacement for the core skill. The core skill
can be installed and used by itself.

For a manual installation, clone the published bundle with
`git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git`, then copy
`git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git`, then copy
both complete folders from that checkout's `skills/` into `~/.agents/skills/`.
Read both copied `VERSION` files: core should be `0.2.7` and adoption `0.1.16`.
Read both copied `VERSION` files: core should be `0.2.8` and adoption `0.1.16`.
For a repository-scoped installation, copy both into
`.agents/skills/` at the project root instead. Use one scope to avoid duplicate
skill entries. Check existing folders and review changes before upgrading; retain
Expand All @@ -46,14 +46,14 @@ If either skill is already installed, [review the upgrade guidance](#upgrading)
before copying files. For a first installation:

```sh
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git
cd context-docs
mkdir -p ~/.claude/skills
cp -r skills/context-docs skills/adopt-context-docs ~/.claude/skills/
cat ~/.claude/skills/context-docs/VERSION ~/.claude/skills/adopt-context-docs/VERSION
```

The version output should be `0.2.7` followed by `0.1.16`.
The version output should be `0.2.8` followed by `0.1.16`.
Keep both folders side by side: the adoption skill reads its sibling core skill.
Invoke a skill as `/context-docs` or `/adopt-context-docs`, or describe the task
and let Claude select it. The packaged `agents/openai.yaml` is Codex metadata and
Expand Down Expand Up @@ -85,7 +85,7 @@ CLI observations and limits. Behavior on other clients has not been evaluated.
For development work, deliberately select a reviewed source branch or commit and
read its `VERSION` files before copying packages. Copying from a working checkout selects its contents rather than the published
bundle and may include unreleased edits. Preserve existing customizations and use one installation
scope. The everyday instructions above remain pinned to v0.2.7.
scope. The everyday instructions above remain pinned to v0.2.8.

## Cursor (experimental)

Expand Down Expand Up @@ -115,7 +115,7 @@ Cursor reads, copy both complete folders from the published tag into one scope:

```sh
(
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git &&
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git &&
cd context-docs &&
mkdir -p ~/.cursor/skills &&
test ! -e ~/.cursor/skills/context-docs &&
Expand All @@ -128,7 +128,7 @@ Cursor reads, copy both complete folders from the published tag into one scope:
The sequence stops at the first failure. A failed clone, for example into an
existing `context-docs` folder, copies nothing. The guard copies nothing if either
skill folder already exists; follow the [upgrade guidance](#upgrading) instead.
Expect `0.2.7` followed by `0.1.16`; no version output means installation did
Expect `0.2.8` followed by `0.1.16`; no version output means installation did
not complete.
For one repository only, use `.cursor/skills/` at its root instead. These
documented locations were not exercised in the trial.
Expand Down Expand Up @@ -199,7 +199,7 @@ completed both fresh behavioral cases: adoption in 160.531 seconds and refresh i
instruction loading remains unverified. The report retains the refresh final
answer's unsupported link-verification claim and the limits of timeout comparisons.
The parent model remained `gemini-3.8-flash-medium`; the account tier was unknown.
Core **0.2.7** and adoption **0.1.16** remain unchanged. The follow-up used a
That follow-up kept core **0.2.7** and adoption **0.1.16**. It used a
task-specific read-only command helper and permission note, not a skill-package
adapter or an installation requirement. These independent cases do not establish
a repeatable end-to-end workflow or automatic instruction loading.
Expand All @@ -215,7 +215,7 @@ project root:
test ! -L .agents/skills/context-docs &&
test ! -e .agents/skills/adopt-context-docs &&
test ! -L .agents/skills/adopt-context-docs &&
git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git context-docs-skills &&
git clone --branch v0.2.8 https://github.com/jaredchu/context-docs.git context-docs-skills &&
mkdir -p .agents/skills &&
cp -r context-docs-skills/skills/context-docs context-docs-skills/skills/adopt-context-docs .agents/skills/ &&
cat .agents/skills/context-docs/VERSION .agents/skills/adopt-context-docs/VERSION
Expand All @@ -224,10 +224,9 @@ project root:

The sequence stops on the first failure and refuses existing skill folders or
symlinks. A failed clone copies nothing. The new `context-docs-skills/` folder is
the source checkout; it is not the active skill directory. Expect `0.2.7` then
the source checkout; it is not the active skill directory. Expect `0.2.8` then
`0.1.16`. For existing installations, [review upgrades](#upgrading) first.
The trial copied these same complete packages locally; the network clone sequence
is checked with a simulated clone, not a new authenticated installation.
The earlier CLI trial used v0.2.7. Tests for the v0.2.8 commands use a simulated clone.

**Other locations (documented, untested).** Google's [skills reference](https://antigravity.google/docs/skills)
lists `~/.gemini/config/skills/` as the shared global location. It also lists
Expand Down
13 changes: 7 additions & 6 deletions docs/project-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Context Docs packages a Markdown maintenance workflow for people without an
established way to preserve project knowledge across AI sessions. Keep useful
decisions, current work and next steps accurate with little manual organization.
Standalone experimental **v0.2.7** is published. The owner separately authorized
Standalone experimental **v0.2.8** is published. The owner separately authorized
website deployment and later selected automatic website deployment from `main`;
installed upgrades remain separate actions.

Expand All @@ -19,11 +19,12 @@ and evidence IDs when those records explain a project issue.

## Current focus

The [unreleased v0.2.8 candidate](releases/v0.2.8.md) clarifies
The [v0.2.8 experimental prerelease](releases/v0.2.8.md) clarifies
[shared-context writer handoff](../skills/context-docs/SKILL.md#make-the-smallest-useful-update)
and [private journal payload delivery](../skills/context-docs/references/event-journal.md#capture-during-maintenance).
The event helper and adoption skill keep their existing behavior. Published
installation commands still select v0.2.7.
The published bundle uses core 0.2.8 and adoption 0.1.16. Installation
commands select v0.2.8. The isolated package check passed, and the public
skills.sh core listing still matched v0.2.7 on the read-only recheck.

**Experimental Antigravity support, validated through CLI; App and IDE not
separately tested** is published from **`4093383`** after the owner's commit,
Expand Down Expand Up @@ -426,8 +427,8 @@ transfer documentation follow-up are complete; no additional skill fix is select
The earlier technical minimalist UI/UX and identity reboot, abstract C logo and README
artwork were deployed from `92042e9`; the [website record](../site/README.md#latest-deployment)
retains successful source CI, Pages jobs and artifact/live checks. The skill
release remains v0.2.7 at `00c4b51`. The owner-retained Cloudflare analytics beacon
is the only observed live HTML difference from the repository build.
release at that point was v0.2.7 at `00c4b51`. The owner-retained Cloudflare
analytics beacon was the only observed live HTML difference for that build.
The isolated skills.sh install passed at v0.2.7 publication, but public page checks
then matched v0.2.6 after a bounded wait. Content refresh remains unverified;
do not treat HTTP 200 telemetry as an updated page or repeat installs/replay telemetry.
Expand Down
6 changes: 3 additions & 3 deletions docs/releases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ including an isolated skills.sh refresh and full page-content verification.

## v0.2.x

- **[v0.2.8 candidate](v0.2.8.md):** core 0.2.8 and adoption 0.1.16,
with isolated package checks and the publication steps still pending.
- **[v0.2.8](v0.2.8.md):** core 0.2.8 and adoption 0.1.16. The current install
instructions select this experimental prerelease.
- **[v0.2.7](v0.2.7.md):**
[local preparation](v0.2.7-validation.json), [publication](v0.2.7-publication.json),
[qualified simplification checks](../../evals/simplification/2026-10-26/README.md)
and [current evidence overview](../evaluation-results.md#more-recent-studies).
Everyday installation is pinned to this bundle; installed upgrades remain separate.
Everyday installation selected this bundle until the v0.2.8 pin update.
- **[v0.2.6](v0.2.6.md):**
[preparation](v0.2.6-validation.json), [publication](v0.2.6-publication.json),
[installed upgrade](../../.context/events/installed-v026-upgrade-20261019.jsonl),
Expand Down
28 changes: 14 additions & 14 deletions docs/releases/v0.2.8.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# v0.2.8 candidate
# v0.2.8 experimental prerelease

Prepared 21 November 2026 from source `9509321`. The candidate bundles
**Context Docs 0.2.8** and **Adopt Context Docs 0.1.16**. Everyday
installation still selects the published [v0.2.7 bundle](v0.2.7.md).
The [experimental prerelease](https://github.com/jaredchu/context-docs/releases/tag/v0.2.8)
was published on 22 November 2026 from `95e0a44`. It bundles **Context Docs
0.2.8** and **Adopt Context Docs 0.1.16**. The installation instructions
now select this bundle. Previous bundle: [v0.2.7](v0.2.7.md).

## Changes

Expand All @@ -14,9 +15,8 @@ installation still selects the published [v0.2.7 bundle](v0.2.7.md).
- Send optional journal events through standard input. When a payload
needs a file, use an authorized private scratch path outside the
checkout and journal directory.
- Keep the site badge tied to the source release status. While core 0.2.8
is unreleased, the site identifies it as such alongside the published
v0.2.7 install instructions.
- Distinguish an unreleased source version from the published install
bundle during release preparation.

The bundle includes the existing
[adoption skill 0.1.16](../../skills/adopt-context-docs/SKILL.md). The
Expand All @@ -38,10 +38,10 @@ handoff remain unverified.

## Publication and upgrades

Keep public install instructions on the published bundle until the new
tag is available. After publication is authorized, validate the exact release
commit, coordinate the install-pin switch, and follow the
[release checklist](../../CONTRIBUTING.md#release-checklist) for the separate
skills.sh refresh and page verification. Existing users can follow the
[upgrade guide](../getting-started.md#upgrading) when they choose to install
a published update.
Both public source archives and a separate isolated, project-scoped install
matched all 16 verified skill files. The skills.sh install telemetry request
returned HTTP 200. The core listing still matched v0.2.7 on a later
read-only recheck. The adoption listing matched the bundled 0.1.16 instructions.

Follow the [upgrade guide](../getting-started.md#upgrading) to preserve
existing project context and settings when upgrading.
2 changes: 1 addition & 1 deletion site/compare.html
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<h1>Why use<br><span>Context Docs?</span></h1>
<p class="guide-lead">You may already have enough. Codex and Claude Code provide instructions and memory, and both can maintain project documents. Context Docs packages a reusable way to decide what to keep and how to maintain it.</p>
<p class="guide-meta">Source review: <time datetime="2026-10-24">October 24, 2026</time> · Copy revised: <time datetime="2026-10-26">October 26, 2026</time><br>Context Docs reviewed: core 0.2.6 / adoption 0.1.15 · Experimental<br>Documentation research, not a comparative benchmark</p>
<p class="compare-bridge">Current published bundle: <a href="https://github.com/jaredchu/context-docs/blob/main/docs/releases/v0.2.7.md">v0.2.7</a> (core 0.2.7 / adoption 0.1.16). This comparison has not been rerun.</p>
<p class="compare-bridge">Current published bundle: <a href="https://github.com/jaredchu/context-docs/blob/main/docs/releases/v0.2.8.md">v0.2.8</a> (core 0.2.8 / adoption 0.1.16). This comparison has not been rerun.</p>
</header>

<section class="guide-section" aria-labelledby="native-title">
Expand Down
Loading
Loading