docs: rewrite README hero + sections to remove sentrux echoes#15
Closed
singaraiona wants to merge 8 commits into
Closed
docs: rewrite README hero + sections to remove sentrux echoes#15singaraiona wants to merge 8 commits into
singaraiona wants to merge 8 commits into
Conversation
Phase-scoped skills layered on the existing raysense MCP server,
packaged as a Claude Code plugin alongside the crate. Layout
mirrors sentrux's: marketplace manifest at the repo root, plugin
sources under ./claude-plugin/.
.claude-plugin/marketplace.json # source -> ./claude-plugin
claude-plugin/
.claude-plugin/plugin.json
.mcp.json # registers `raysense --mcp`
skills/
raysense-bootstrap/SKILL.md # session start: scan + baseline + memory
raysense-impact/SKILL.md # before edits: blast radius + coupling
raysense-verify/SKILL.md # after edits: rescan + rule check + diff
raysense-audit/SKILL.md # on demand: architecture + dsm + evolution
Each skill is a short markdown playbook over MCP tools that already
exist in src/mcp.rs:137 (verified: every raysense_* name referenced
across all four SKILL.md files resolves in the tool registry).
Multi-codebase isolation is cwd-driven: every skill passes
path: $CWD; per-project state stays in <repo>/.raysense/. Two CC
sessions on two repos = two MCP processes, two on-disk state trees,
zero cross-project bleed.
No new Rust code; cargo test still 123/123 green.
Install path:
cargo install raysense
/plugin marketplace add RayforceDB/raysense
/plugin install raysense
Co-authored-by: Anton <anton.kundenko@gmail.com>
* build: source rayforce from upstream at pinned SHA
The vendored rayforce/ copy had drifted from upstream and shipped
incomplete (no Makefile). Replace it with an auto-clone flow that
sources rayforce from the pinned SHA in `.rayforce-version`.
Resolution order in build.rs:
1. RAYFORCE_DIR set -> link external librayforce.a (dev mode,
unchanged)
2. vendor/rayforce/ -> source bundled inside the published
Makefile exists .crate tarball (or populated by CI before
`cargo package`); copy to OUT_DIR, build
3. neither -> shallow clone upstream at the pinned SHA
into OUT_DIR, build there
All `make lib` work happens in `OUT_DIR/rayforce-build/`. The source
tree is never modified — required for `cargo package` to verify clean.
CFLAGS override: drop `-march=native` and `-Werror` from the upstream
RELEASE_CFLAGS so the produced .a runs on any CPU of the target arch
and downstream builds don't break on new compiler warnings.
Cargo.toml `include` whitelists vendor/rayforce/{Makefile,LICENSE,
src/**,include/**} so the published .crate ships the source needed
for offline downstream builds. .gitignore drops vendor/ from tracking;
CI populates it explicitly before `cargo package` (publish.yml).
Pin format: single-line hex SHA in .rayforce-version. Bump by editing
the file and running `cargo clean -p raysense && cargo build`.
Verified locally:
- cargo test: 123/123 green
- cargo fmt --check: clean
- cargo package: 167 files, 838 KiB compressed (under crates.io 10
MiB limit). Verification build passes — source dir unmodified.
* fmt: collapse read_pin one-liner per rustfmt
---------
Co-authored-by: Anton <anton.kundenko@gmail.com>
Reframed around the actual problem (AI agents drift codebase architecture at machine speed; you can't see it from a diff) instead of leading with feature lists. Replaced the "What it measures" spec-sheet bullet wall with two sharper sections: - "One quality signal" — the six A-F dimensions with a one-line explanation each, ending with the ungameable claim. - "What you get" — the actual differentiators (live treemap, baselines + what-if, splayed memory, test gaps, evolution, language coverage), not the metric taxonomy. Killed the broken docs/agent-loop-integration.md link from the earlier draft — the plugin install IS the integration story now, inlined under "For coding agents". Updated "Building from source" to reflect the new auto-clone flow: mentions .rayforce-version, RAYFORCE_DIR, and the git/make/cc prerequisites (the prior text claimed "no external setup, no submodules" which is no longer accurate). Added a "Built on Rayforce" section that promotes the sibling project and explains why it shows up under the hood (columnar runtime → instant repeat queries against a snapshot). Language count corrected to 45 (40 plugin catalog entries + 5 tree-sitter built-ins, verified against src/scanner.rs). Co-authored-by: Anton <anton.kundenko@gmail.com>
Two changes to README: 1. Replace every em-dash and en-dash with the plain hyphen, keeping the prose readable by re-flowing into commas, parentheses, or colons where a single hyphen would be awkward. House style is now ASCII-only punctuation (-, ', ") in all written output. 2. Add the Rayforce logo at the head of the "Built on Rayforce" section, theme-aware via <picture> with media query: light SVG for dark mode, dark SVG for light mode. Linked to upstream raw URLs so the logo always tracks rayforce/master without raysense needing to vendor a copy. No content changes beyond punctuation and the logo block. Co-authored-by: Anton <anton.kundenko@gmail.com>
PR #10 merged before two follow-up commits landed; this brings the intended end state onto main: 1. Logo files copied from ../rayforce/docs into raysense's own docs/. Both projects are owned by the same author, no attribution issue. raysense is now self-contained for README assets and no longer depends on rayforce/master staying public or stable. 2. README references them via relative path, which works in: - GitHub README rendering on main - GitHub PR preview on a feature branch - crates.io README rendering once `docs/*.svg` ships in the .crate 3. <picture> now declares both light and dark sources explicitly (the prior single-source-plus-fallback worked on github.com but was fragile on some other markdown renderers): dark theme -> logo-light.svg (white mark, visible on dark bg) light theme -> logo-dark.svg (navy mark, visible on light bg) 4. Cargo.toml `include` whitelist updated with `docs/*.svg` so the published .crate ships the SVGs. Co-authored-by: Anton <anton.kundenko@gmail.com>
Rewrite publish.yml to be triggered by `vX.Y.Z` tag pushes (or a
manual dispatch for dry-run). On a real release tag, the workflow:
1. Verifies the tag matches Cargo.toml's version field, fails
loudly if they drift.
2. Vendors rayforce at the pinned SHA (existing behavior).
3. Runs `cargo test`.
4. Publishes to crates.io, idempotent (skips if the version is
already there).
5. Generates release notes by grouping conventional-commit
subjects since the previous tag into Features / Bug fixes /
Performance / Refactoring / Documentation / Build & CI /
Chores / Other, with a "Full changelog" link.
6. Creates the GitHub Release with those notes (or updates the
notes on a pre-existing release).
7. Smoke-tests the published crate (`cargo install raysense
--version <X>` plus a downstream `cargo check`).
Bug fixes vs the prior workflow:
- `version_of` previously read from `crates/raysense/Cargo.toml`,
which never existed in the single-crate layout. Now reads from
the root Cargo.toml.
- Trigger was `release: published`, which required hand-creating
the GitHub Release before any automation could run. Now the
tag IS the trigger, and the release is created automatically
with auto-generated notes.
Manual dry-run path kept via `workflow_dispatch` with
`dry_run: true` (default) -- runs `cargo package` + `cargo publish
--dry-run` and skips release creation and smoke test.
Permissions: workflow now declares `contents: write` so the
GITHUB_TOKEN can call `gh release create` / `gh release edit`.
Prerequisite for the next real release: `CARGO_REGISTRY_TOKEN`
secret must be set on the repo (it was already referenced by the
prior workflow).
Co-authored-by: Anton <anton.kundenko@gmail.com>
The CI vendor step clones rayforce into vendor/rayforce/ at run time, but vendor/ is gitignored (the source of truth lives in upstream rayforce + .rayforce-version, not the committed tree). cargo package would otherwise refuse to ship what it sees as 'uncommitted changes' from those untracked files. Caught by the dry-run dispatch on PR #12's merge commit; the workflow exited with status 101 listing every vendor/rayforce/ file as untracked. Co-authored-by: Anton <anton.kundenko@gmail.com>
A separate review against sentrux.dev showed the README copy mirrored
sentrux's cadence and signature words too closely. Rewrite to remove
the overlap while keeping the same factual content. Specific changes:
- Hero h1 + paragraph: dropped the "AI ... at machine speed.
Codebase ... at machine speed too." structure. Replaced with an
X-ray framing that comes from raysense's own POV.
- "## The problem" -> "## Why". Body rewritten without echoing
sentrux's "the problem nobody talks about" framing.
- "## One quality signal" -> "## Grading model". The
"N dimensions. One score." cadence is gone; replaced with
"Six dimensions, each graded A through F. The overall score,
0 to 100, is their weighted aggregate."
- Dropped "ungameable" verbatim; replaced with "The score moves
with structure, not with cosmetics: adding tests or shuffling
files around will not lift it."
- "## What you get" -> "## Capabilities".
- "## For coding agents" -> "## Agent integration".
No factual claim changed. The capability list, install commands,
plugin instructions, and Built-on-Rayforce section are unchanged.
This keeps the README and the new site/index.html prose in sync;
both come from raysense's own voice now, not sentrux's.
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.
Why
A separate review against sentrux.dev showed the README copy mirrored sentrux's cadence and signature words too closely. This PR rewrites the affected sections in raysense's own voice while keeping every factual claim intact.
Changes
What did not change
Pairs with #14
The site landing page in PR #14 went through the same rewrite. The README and site now share voice.