aimem: mirror the ISO 24495-1 plain-language pass

[harshavardhana]

Ports the aimem skill-template changes from miniohq/aimem#167, which applied the ISO 24495-1 Plain Language standard across that repository's documentation. Mirroring skill changes here is a standing requirement.

The substantive change

SKILL.md advertised references/navigation.md as covering "how to identify the bucket/region/endpoint of your mount". navigation.md states the opposite — those commands locate the mount only, and nothing on the mount exposes the bucket, region, or endpoint. An agent following that pointer to answer "which bucket am I on?" landed on a page telling it the question couldn't be answered there.

That's a behavioural defect in the installed skill, not a wording preference, and it's the main reason this mirror matters:

-- **`references/navigation.md`** — how to identify the bucket/region/endpoint
-  of your mount, and the conventional layout of files at the root.
+- **`references/navigation.md`** — how to locate your mount and the
+  conventional layout of files at its root.

The rest

The six reference pages get sentence-level clarity fixes with no change in meaning — long multi-clause sentences split, an em-dash aside moved out from between a subject and its verb, a passive construction given its actor. Total diff is 17 insertions / 17 deletions across 7 files.

Divergences deliberately preserved

This repo's copies are not verbatim upstream, and the port keeps every existing difference:

• SKILL.md keeps this repo's extra front matter (license, compatibility, metadata) and omits the {aimem_version} / {generated} placeholders, which the aimem binary substitutes at install time and which have no meaning here.
• SKILL.md and references/navigation.md keep this repo's better mount lookup — findmnt -n -o TARGET -S aimem plus the awk fallback — rather than upstream's findmnt -S aimem form. Upstream is arguably the one that should adopt this.

Verified after porting: the only remaining differences against the post-#167 templates are those three, and no {...} placeholder leaked into any file.

AGENTS.preamble.md is not mirrored: it's the aimem read-time overlay injected into instruction files by the binary, not part of the installable skill.

Summary by CodeRabbit

• Documentation
  • Clarified navigation guidance for locating mounted storage.
  • Improved instructions for annotation-directory errors and sharing agent context.
  • Documented metadata namespace behavior and persistence.
  • Clarified that agent-native entries and annotations are stored separately from object content.
  • Explained default search output and content-match formatting.
  • Documented concurrent-writer behavior, including last-close-wins uploads and bucket-level overwrites.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 923cabd9-5a64-4b2a-b501-7cd5272512b4

📥 Commits

Reviewing files that changed from the base of the PR and between d543829 and 80513e9.

📒 Files selected for processing (7)

• aimem/SKILL.md
• aimem/references/annotations.md
• aimem/references/memory.md
• aimem/references/metadata.md
• aimem/references/navigation.md
• aimem/references/search.md
• aimem/references/workspace.md

---

📝 Walkthrough

Walkthrough

The documentation clarifies AIStor Memory mount navigation, agent context paths, metadata behavior, annotation guidance, search output formats, and concurrent-writer behavior.

Changes

AIStor Memory documentation

Layer / File(s)	Summary
Mount and agent context guidance aimem/SKILL.md, aimem/references/navigation.md, aimem/references/memory.md	The documentation defines mount location, agent-native surfaces, object annotations, and conventional context paths.
Metadata and annotation guidance aimem/references/annotations.md, aimem/references/metadata.md	The documentation clarifies annotation punctuation and observe-only reflected metadata namespaces.
Search output and concurrent writes aimem/references/search.md, aimem/references/workspace.md	The documentation specifies search output formats and last-close-wins behavior for concurrent writes.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• minio/skills#4: Both changes update search documentation and its skill reference.
• minio/skills#5: Both changes update mount-location and search-output guidance.

Poem

A rabbit hops through mounted space,
Finding clearer paths in place.
Metadata rests where agents see,
Search lines march orderly.
Last close wins the writable race—
Documentation keeps the pace.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the documentation-focused plain-language edits mirrored into the aimem skill template.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}