From fe759adf7daf3d267ba9125db7bdc6bded076671 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Thu, 13 Aug 2026 09:41:26 -0500 Subject: [PATCH 1/4] root and k8s --- AGENTS.md | 91 ++++++++++++++++ CLAUDE.md | 1 + config.toml | 6 ++ content/operate/kubernetes/AGENTS.md | 151 +++++++++++++++++++++++++++ content/operate/kubernetes/CLAUDE.md | 1 + 5 files changed, 250 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 content/operate/kubernetes/AGENTS.md create mode 100644 content/operate/kubernetes/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..bbed14d07a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# Redis docs — conventions for AI-assisted editing + +Conventions for drafting and editing pages in this repository. Everything here is a +property of the site or of the house style, so it holds everywhere. + +**This file stays small on purpose.** It carries only what is true across every product. +As soon as a rule needs a product-specific caveat, it belongs in that product's +`AGENTS.md` instead — where it can be stated with its exception, and loaded only by +sessions editing those pages. + +Product directories under `content/operate/` and `content/develop/` add their own +`AGENTS.md` covering terminology and disclosure. Read it before editing prose in one of +those directories. Where it conflicts with this file, the product file wins. + +**Disclosure rules are not uniform across this repo.** Open source documentation under +`content/develop/` and `content/commands/` legitimately links to source code and +documents implementation internals, because the implementation is public and is part of +the product. Commercial product directories do not. Never carry a disclosure rule from +one product's pages into another's — check that product's `AGENTS.md`. + +## Before applying any rule here + +If a term, structure, or frontmatter shape is already used consistently across this +section's pages, that usage wins until it is deliberately changed everywhere at once. A +single page that disagrees with its neighbors is a page to fix; twenty that agree are a +convention. + +Do not normalize an inconsistency you noticed while doing unrelated work — note it and +move on. Where a rule below says otherwise for a specific term, that rule wins. + +## Style + +- Google developer documentation style. +- Lead with the takeaway. The most useful sentence goes first. +- Present tense, active voice, second person. "The operator detects the change", not + "changes are detected". +- Short sentences. Split anything with three clauses. +- Plain verbs: `use`, not `utilize`. Contractions are fine. +- Sentence-case headings. Procedure titles start with a verb: "Create a role". +- Numbered steps, one action per step. Call them **steps**, never "flows". +- Expand every acronym on first use in a page, including familiar ones: RBAC, CRD, TLS. +- No marketing register: not "seamless", "powerful", "simply", "easily", "just". +- No directional language ("above", "below", "on the left"). Link to the thing. +- Prefer `replica`, `allowlist`, `denylist`. + +## Prose form and code form are different + +Use the readable form in prose and the literal identifier only where the reader types +it, or once in parentheses on first mention. + +Configuration keys, API fields, custom resource kinds, command names, and endpoint paths +are never reworded, re-cased, or pluralized to fit a sentence. If a sentence reads badly +around a literal, rewrite the sentence. + +## Site mechanics + +- **Cross-references use the relref shortcode**, not markdown paths: + `{{< relref "/operate/rs/clusters/new-cluster-setup" >}}`. A broken relref fails the + build. Link text is descriptive — never "click here" or a bare URL. +- **Preserve shortcodes, frontmatter, and code fences verbatim.** Do not reformat them. +- **Frontmatter**: copy the shape from a sibling page in the same directory rather than + composing one. `title` and `linkTitle` are effectively universal; `description`, + `weight`, and `categories` are common but not required — a page without one is not a + defect to fix. Key casing is inconsistent across the corpus (`title` and `Title`, + `linktitle` and `linkTitle`) — match the directory you are in and do not normalize. +- **Inline HTML comments are for open items only** — a TODO or an unresolved question + someone still has to act on. Never narrate a resolved decision or record where content + came from. Delete a comment when its item is resolved rather than rewriting it as a + note. Ticket references such as `` stay. +- **Examples must be runnable by the reader.** Use angle-bracket placeholders such as + ``, and never real credentials, addresses, or customer data. +- **New pages**: check whether the topic already exists and prefer extending or + cross-linking an existing page. Prefer consolidated pages with H2 sections over many + small files. Never leave a new page unlinked from its section index. + +## Editing scope + +Edit only what was asked. If a neighboring page or section also needs work, name it in +one sentence and stop. + +An editorial pass should leave a page shorter, not longer. Do not add summary sections, +boilerplate introductions, or transitions the original did not have. If a section needs +new material to be usable, say so instead of writing it. + +## Flag rather than decide + +- **A technical fact looks wrong.** Never silently correct a command, value, field name, + port, or version-specific fact. Say what looks wrong and leave it. +- **The change would remove or soften a documented limitation.** Weakening a published + "no" is a product claim, not an edit. +- **A term appears that this file does not cover.** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/config.toml b/config.toml index f81bec6f0d..230dee5230 100644 --- a/config.toml +++ b/config.toml @@ -27,6 +27,12 @@ ignoreFiles = [ "/__pycache__/", # Python bytecode cache "/models/", # Hugot model cache "/\\.transformers-cache/", # TransformersPHP cache + # AI-audience convention files. These live beside the pages they describe so + # coding agents load them by directory, but they are not documentation and must + # never render: Hugo turns any .md under content/ into a published page. + "AGENTS\\.md$", + "CLAUDE\\.md$", + "CLAUDE\\.local\\.md$", ] [related] diff --git a/content/operate/kubernetes/AGENTS.md b/content/operate/kubernetes/AGENTS.md new file mode 100644 index 0000000000..bebee0693e --- /dev/null +++ b/content/operate/kubernetes/AGENTS.md @@ -0,0 +1,151 @@ +# Redis Software for Kubernetes docs — conventions for AI-assisted editing + +These pages document the operator-based deployment of Redis Software on Kubernetes and +OpenShift. The self-managed product is documented under `content/operate/rs/` and the +managed service under `content/operate/rc/`; both have their own conventions. + +Read the repository-root `AGENTS.md` first for style and site mechanics. This file adds +terminology and disclosure rules for this directory, and wins where the two conflict. + +## Product name — a deliberate transition, not an inconsistency to resolve + +The current product name is **Redis Software for Kubernetes**. The legacy name is +"Redis Enterprise for Kubernetes". + +These pages are mid-rebrand: most current pages still carry the legacy name. **That is +expected.** + +- **New and rewritten content uses "Redis Software for Kubernetes".** +- **Do not rename the legacy occurrences.** Rebranding is a deliberate pass across the + whole section, not something to do while editing a page for another reason. + +**This overrides the root file's "match the corpus" rule for this term.** The legacy name +is more common here, so following the majority is wrong. Treat the name as settled and +the pages as lagging. + +_This section is transitional. Once the rebrand pass is complete and the legacy name no +longer appears in this directory, delete it and keep only the name itself._ + +When linking to a page whose `title` still carries the legacy name, use the current +name in your link text — `relref` resolves by path, not by title. + +## Identifiers that never change + +Custom resource kinds are used exactly as they appear in the API, legacy name and all: + +`RedisEnterpriseCluster`, `RedisEnterpriseDatabase`, `RedisEnterpriseUser`, +`RedisEnterpriseACL`, `RedisEnterpriseRole`, `RedisEnterpriseRoleBinding`, +`RedisEnterpriseClusterRole`, `RedisEnterpriseClusterRoleBinding`, +`RedisEnterpriseActiveActiveDatabase`, `RedisEnterpriseRemoteCluster`. + +The same holds for abbreviations — **REC**, **REDB**, **REAADB**, **RERC** — and for +field paths such as +`RedisEnterpriseCluster.spec.accessControl.policy.allowREDBRolesPermissions`. + +Never "modernize" an identifier to match the product name. The API is the API. + +## Say "databases", not "BDB" + +Do not write "BDB" or "BDBs" in prose. Write "databases", or "databases created +directly through the REST API" where that distinction matters. + +- **REDB** is fine — it is the custom resource name. +- A literal `bdb` in an API path, request body, or placeholder such as `` + stays as-is. It is what the reader types. + +## Roles + +Use the readable form in prose — "cluster admin" is the established usage — and the +role ID only where the reader types it, or once in parentheses on first mention. + +Role names as *defined* appear in title case in reference tables and examples ("Cluster +Member", "DB Viewer"). Match the surrounding page: title case where a specific named +role is being identified, lowercase prose where you are describing who does something. + +## Container image paths differ by registry + +Release notes and deployment pages reference images from two registries that name the +same components differently. Match the path style to the registry being documented. + +| Component | Red Hat Connect | Docker Hub | +| --- | --- | --- | +| Redis Software node | `redis-enterprise` | `redis` | +| Operator | `redis-enterprise-operator` | `operator` | +| Services Rigger | `services-manager` | `k8s-controller` | +| Call-home client | `call-home-client` | `re-call-home-client` | + +Getting this wrong produces a path that looks plausible and does not resolve. Check the +registry before writing or editing an image reference. + +## Release codenames are internal + +Operator releases carry internal codenames. **None of them appear anywhere in published +content, and none should.** Refer to releases by version number. + +## Versioned content + +Version-specific pages live in sibling folders such as `7.22/`, `7.8.6/`, and `8.0/`. +The unversioned root is the current content. + +Default every edit to the current content. When updating shared behavior, check whether +the change applies across versions or only to the current one, and never propagate a +current-version change backward into a snapshot. + +## Document current behavior only + +Do not foreshadow planned support, future feature expansions, or roadmap items — even +when a specification, an internal document, or a subject-matter expert mentions them. +Planned work slips, changes shape, or gets cut, and removing a promise from a published +page is visible to customers. + +- Wrong: "Support for multi-namespace deployments is planned for a future release." +- Wrong: "This limitation is expected to be lifted in a later operator version." +- Right: state the current limitation flatly, with no forecast — for example, "custom + resources of this kind are reconciled only in the operator namespace." + +**Carve-out — deprecation and removal notices are correct and expected.** The rule bans +promising something the reader will *gain*, not telling them what is going away. +Customers need lead time to migrate or upgrade, and a warning is sometimes published +ahead of the deprecation itself to give them that time. + +- Right: "Support for this platform will be removed in a future release." +- Right: "This field is deprecated and will be removed in a future release. Use + `` instead." + +The test: does the sentence tell the reader they will gain something, or lose something? +Gains are out. Losses are in. + +## Do not publish ahead of customer availability + +Content describing a feature does not go live until customers can use it. The gate is +availability to customers — not that the code merged, and not that the field exists in +an internal build. A feature that is cut or deferred takes its documentation with it: +remove the content rather than softening it into a promise. + +Drafting ahead is normal. Draft, verify, open the pull request, and hold it. + +## The operator source is private + +The operator source repository is not public, so a file path or repository URL is a dead +end for every reader of these pages. Where a statement was only defensible because it +cited code, it either stands on its own as documented behavior or it comes out. + +"Check the controller for the valid values", in any phrasing, means the page has a real +gap. Flag it rather than shipping it. + +Do not document internal implementation detail — reconcile-loop internals, internal +service names, or controller-private fields — beyond what a user sets in a custom +resource or observes in its status. + +Published pages carry no audit trail. Strip verification notes, "verified against" +lines, source lists, and freshness dates. + +## Flag rather than decide + +- A custom resource field, default, or image tag cannot be confirmed. Operator fields + and defaults shift between releases; never infer one. +- Internal material contradicts a published page. The internal version does not + automatically win — it may describe unreleased behavior or a different operator + version than the page documents. +- A version or release boundary is unclear. These pages describe shipped behavior. +- A term appears that this file does not cover. diff --git a/content/operate/kubernetes/CLAUDE.md b/content/operate/kubernetes/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/content/operate/kubernetes/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From cf5f630884e01f7b911ee93e45f3e639bff631c5 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 17 Aug 2026 15:26:46 -0500 Subject: [PATCH 2/4] RS files --- content/operate/rs/AGENTS.md | 150 +++++++++++++++++++++++++++++++++++ content/operate/rs/CLAUDE.md | 1 + 2 files changed, 151 insertions(+) create mode 100644 content/operate/rs/AGENTS.md create mode 100644 content/operate/rs/CLAUDE.md diff --git a/content/operate/rs/AGENTS.md b/content/operate/rs/AGENTS.md new file mode 100644 index 0000000000..cb88938fce --- /dev/null +++ b/content/operate/rs/AGENTS.md @@ -0,0 +1,150 @@ +# Redis Software docs — conventions for AI-assisted editing + +These pages document **Redis Software** — the self-managed product installed on VMs, +bare metal, or containers. The Kubernetes operator is documented under +`content/operate/kubernetes/` and the managed service under `content/operate/rc/`; +both have their own conventions. + +Read the repository-root `AGENTS.md` first for style and site mechanics. This file +adds terminology and disclosure rules for this directory, and wins where the two +conflict. + +## Product names + +| Use | Not | Note | +| --- | --- | --- | +| Redis Software | Redis Enterprise Software, Redis Enterprise | Current name. Use it in all current prose. | +| Redis Software | RS | `RS` is internal shorthand and the URL slug (`/operate/rs/`). Never use it in customer-facing prose. | + +**Versioned folders predate the rebrand.** Pages under `7.4/`, `7.8/`, and `7.22/` +still say "Redis Enterprise Software" and "Redis Enterprise". Leave that wording +alone. Renaming is a deliberate repo-wide pass, not something to do while editing a +page for another reason. + +When linking to a page whose `title` still carries the old name, use the current name +in your link text — `relref` resolves by path, not by title. + +## Active-Active databases + +Active-Active databases were formerly called CRDBs, and both forms are correct in +different places. This is the most commonly mis-corrected convention in this +directory, so check which surface you are editing. + +- **Prose** — "Active-Active database". Where a gloss helps, write "(formerly known as + CRDB)". CRDB is a former name, not a current synonym. +- **REST API reference titles** — **keep CRDB.** The API surface is named `crdb`, and + the object pages are titled "CRDB object", "CRDB database config object", and so on. + Retitling one makes it the outlier among its siblings. +- **Code, identifiers, endpoints** — always literal: `crdb-cli`, `/crdbs`, JSON field + names. + +**Never write bare "Active-Active" with no noun.** Qualify it with whichever is +accurate: + +- The whole replicated object is the **Active-Active database**. +- Per-cluster settings are configured **per participating cluster** — for example the + REST `instances[].cluster.certificate_auth` field, or `crdb-cli --instance`. Write + "each participating cluster in the Active-Active database", not "each Active-Active + instance". + +## Roles + +Use the readable form in prose — "cluster admin" is the established usage — and the +role ID only where the reader types it, or once in parentheses on first mention. + +Role names as *defined* appear in title case in the reference tables ("Cluster Member", +"Cluster Viewer", "DB Member", "DB Viewer"). Match the surrounding page: title case +where a specific named role is being identified, lowercase prose where you are +describing who does something. + +## Versioned content + +The unversioned root of this directory (`clusters/`, `databases/`, `references/`) is +the current content. `7.4/`, `7.8/`, and `7.22/` are frozen snapshots carrying a +`bannerText` that names the version. + +Default every edit to the current content. Touch a snapshot only when the change is +specific to that version, and never propagate a current-version change backward into +one. + +## Generated pages — do not hand-edit + +The Cluster REST API reference under `references/rest-api/api-reference/` is generated +from an engineering-owned OpenAPI specification. Edits to those pages are overwritten +on the next regeneration. + +If something there is wrong — a missing property description, an inconsistency between +request and response fields, an outdated product name — report it so it can be fixed in +the specification. Do not patch the generated output. + +## Release notes + +Release notes live under `release-notes/`, grouped by minor line (`rs-8-0-releases/`, +`rs-7-22-releases/`). + +- Build numbers are `-`, for example `8.0.20-19`. +- Titles read `Redis Software release notes 8.0.20-19 (May 2026)`. +- Frontmatter includes `compatibleOSSVersion` and a `weight`. +- Structure: **Highlights**, then **New in this release** (New features, then + Enhancements), then resolved issues, then known limitations. Follow the most recent + notes in the newest release folder; older notes predate the current template. +- A new release also updates `references/supported-platforms.md` and + `references/upgrade-paths.md`. + +## Document current behavior only + +Do not foreshadow planned support, future feature expansions, or roadmap items — even +when a specification, an internal document, or a subject-matter expert mentions them. +Planned work slips, changes shape, or gets cut, and removing a promise from a published +page is visible to customers. + +- Wrong: "Support for this is planned for a future release." +- Wrong: "This limitation is expected to be lifted in 8.4." +- Right: state the current limitation flatly, with no forecast. + +**Carve-out — deprecation and removal notices are correct and expected.** The rule bans +promising something the reader will *gain*, not telling them what is going away. +Customers need lead time to migrate or upgrade, and a warning is sometimes published +ahead of the deprecation itself to give them that time. These pages carry many such +notices deliberately. + +- Right: "Support for TLS 1.1 and earlier will be removed in a future release." +- Right: "This endpoint is deprecated as of Redis Software version 7.2.4 and will be + removed in a future release. Use `` instead." + +The test: does the sentence tell the reader they will gain something, or lose +something? Gains are out. Losses are in. + +## Do not publish ahead of customer availability + +Content describing a feature does not go live until customers can use it. The gate is +availability to customers — not that the code merged, and not that it exists in an +internal build. A feature that is cut or deferred takes its documentation with it: +remove the content rather than softening it into a promise. + +Drafting ahead is normal. Draft, verify, open the pull request, and hold it. + +## The product source is private + +The Redis Software source repository is not public, so a file path or repository URL is +a dead end for every reader of these pages. Where a statement was only defensible +because it cited code, it either stands on its own as documented behavior or it comes +out. + +"Check the implementation for the valid values", in any phrasing, means the page has a +real gap. Flag it rather than shipping it. + +Do not document internal implementation detail — process names, internal service names, +on-disk layouts, or internal field encodings — beyond what a customer configures or +observes. + +Published pages carry no audit trail. Strip verification notes, "verified against" +lines, source lists, and freshness dates. + +## Flag rather than decide + +- Internal material contradicts a published page. The internal version does not + automatically win — it may describe unreleased behavior, an internal rename, or a + different version than the page documents. +- A version or release boundary is unclear. These pages describe shipped behavior. +- A term appears that this file does not cover. diff --git a/content/operate/rs/CLAUDE.md b/content/operate/rs/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/content/operate/rs/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 471c82783bd03b68d06ccdf9d6398010f00b1d2b Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 17 Aug 2026 15:26:57 -0500 Subject: [PATCH 3/4] FF files --- content/develop/ai/featureform/AGENTS.md | 134 +++++++++++++++++++++++ content/develop/ai/featureform/CLAUDE.md | 1 + content/operate/featureform/AGENTS.md | 134 +++++++++++++++++++++++ content/operate/featureform/CLAUDE.md | 1 + 4 files changed, 270 insertions(+) create mode 100644 content/develop/ai/featureform/AGENTS.md create mode 100644 content/develop/ai/featureform/CLAUDE.md create mode 100644 content/operate/featureform/AGENTS.md create mode 100644 content/operate/featureform/CLAUDE.md diff --git a/content/develop/ai/featureform/AGENTS.md b/content/develop/ai/featureform/AGENTS.md new file mode 100644 index 0000000000..5df382f733 --- /dev/null +++ b/content/develop/ai/featureform/AGENTS.md @@ -0,0 +1,134 @@ +# Redis Feature Form docs — conventions for AI-assisted editing + +These pages document **Redis Feature Form**, a feature platform. The documentation is +split across two directories by audience: + +- `content/develop/ai/featureform/` — authoring and serving features: concepts, + quickstart, definitions files, providers, workspaces, querying, serving. +- `content/operate/featureform/` — deploying the product and configuring + authentication. + +This file is duplicated in both directories so that either one loads it on its own. +**Keep the two copies identical** — a change to one is a change to both. + +Read the repository-root `AGENTS.md` first for style and site mechanics. This file adds +terminology and disclosure rules for these directories, and wins where the two conflict. + +## The source is private — the open source carve-out does not apply here + +The root file notes that documentation under `content/develop/` legitimately links to +source code and documents implementation internals, because the products documented +there are open source. **Feature Form is not.** Its source repository is private, so a +file path, repository URL, or "see the implementation" pointer is a dead end for every +reader of these pages. + +These pages currently contain no source links. Do not add one. + +Where a statement was only defensible because it cited code, it either stands on its own +as documented behavior or it comes out. "Check the source for the supported providers", +in any phrasing, means the page has a real gap. Flag it rather than shipping it. + +Published pages carry no audit trail. Strip verification notes, "verified against" +lines, source lists, and freshness dates. + +## Product names + +| Use | Not | Note | +| --- | --- | --- | +| Redis Feature Form | Featureform, Feature form | First mention on a page. | +| Feature Form | Featureform, FF | Every later mention on that page. | +| feature platform | feature store | What the product is. The pages use "feature platform"; "feature store" appears nowhere in them. | + +**"Featureform" as one word is a code identifier, never prose.** It is correct in the +Python package (`import featureform as ff`), in a module path, and in a type name such as +`ff.FeatureformError`. It is wrong in a sentence. + +The command-line tool is `ff`. Use the literal in commands, and never as an abbreviation +for the product in prose. + +## Resource vocabulary + +`concepts.md` defines the resource types and is the canonical source for them. Do not +restate those definitions on another page — link to it. The distinctions below are the +ones most often gotten wrong. + +- **Features and labels have the same shape and different jobs.** A feature is model + input read at inference time. A label is the target value a model is trained to + predict, and feeds offline training rather than online serving. They are not + interchangeable. +- **A dataset registers data that already exists** in an offline store. A + **transformation** produces a new dataset from existing ones. Neither is a "source" — + that word is not a resource type here. +- **A feature view is the only graph resource downstream applications read from.** + Applications do not query features directly. +- **A workspace is the isolation boundary.** Nothing is shared between workspaces. Never + describe a resource as shared, global, or deployment-wide unless the page says so. + +Provider **roles** are literal values — `offline-store`, `online-store`, `compute`, +`streaming` — and are not reworded or capitalized to fit a sentence. A provider fills one +or more roles; it is not "an offline store" in prose where the role name is meant. + +## Materialization is described abstractly — never expose the storage layout + +Feature Form materializes feature values into an online store, typically Redis. Describe +what materialization achieves — that values are populated and available to serve — and +stop there. + +**Never document how those values are laid out in Redis.** No key formats, no key naming +schemes, no hash field names, no reserved metadata fields, no internal encodings. This is +a deliberate decision, not an omission to helpfully fill in: the layout is internal, it +changes without notice, and a reader who builds against it builds on sand. + +The same holds for the planner and the task DAG. What a change causes is documentable; +how the work is scheduled and executed internally is not. + +## Do not weaken the credential claim + +These pages state that Feature Form never stores credentials in any form — not +plaintext, not hashed, not encrypted — and that a provider configuration carries only a +reference to a separately registered secret backend. + +That is a security claim about the product. Do not soften it, qualify it, or restate it +in looser words while editing nearby prose. If something appears to contradict it, flag +it; do not resolve it in the text. + +Examples never contain a real credential, host, or account identifier. A secret reference +in an example is a reference, such as `env:PG_PASSWORD` — not a value. + +## Document current behavior only + +Do not foreshadow planned support, future feature expansions, or roadmap items — even +when a specification, an internal document, or a subject-matter expert mentions them. +Planned work slips, changes shape, or gets cut, and removing a promise from a published +page is visible to customers. + +- Wrong: "Support for additional providers is planned." +- Wrong: "This provider is expected to gain streaming support." +- Right: state which providers and roles are documented today, and stop. + +**Carve-out — deprecation and removal notices are correct and expected.** The rule bans +promising something the reader will *gain*, not telling them what is going away. +Customers need lead time to migrate, and a warning is sometimes published ahead of the +removal itself to give them that time. + +The test: does the sentence tell the reader they will gain something, or lose something? +Gains are out. Losses are in. + +## Do not publish ahead of customer availability + +Content describing a feature does not go live until customers can use it. The gate is +availability to customers — not that the code merged, and not that the capability exists +in an internal build. A feature that is cut or deferred takes its documentation with it: +remove the content rather than softening it into a promise. + +Drafting ahead is normal. Draft, verify, open the pull request, and hold it. + +## Flag rather than decide + +- **A provider, role, or resource field cannot be confirmed** against the documented + behavior. Never infer a supported provider or an accepted argument. +- **An example would need a credential, a real endpoint, or infrastructure detail** to + work as written. +- **Internal material contradicts a published page.** The internal version does not + automatically win — it may describe unreleased behavior or an internal rename. +- **A term appears that this file and `concepts.md` do not cover.** diff --git a/content/develop/ai/featureform/CLAUDE.md b/content/develop/ai/featureform/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/content/develop/ai/featureform/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/content/operate/featureform/AGENTS.md b/content/operate/featureform/AGENTS.md new file mode 100644 index 0000000000..5df382f733 --- /dev/null +++ b/content/operate/featureform/AGENTS.md @@ -0,0 +1,134 @@ +# Redis Feature Form docs — conventions for AI-assisted editing + +These pages document **Redis Feature Form**, a feature platform. The documentation is +split across two directories by audience: + +- `content/develop/ai/featureform/` — authoring and serving features: concepts, + quickstart, definitions files, providers, workspaces, querying, serving. +- `content/operate/featureform/` — deploying the product and configuring + authentication. + +This file is duplicated in both directories so that either one loads it on its own. +**Keep the two copies identical** — a change to one is a change to both. + +Read the repository-root `AGENTS.md` first for style and site mechanics. This file adds +terminology and disclosure rules for these directories, and wins where the two conflict. + +## The source is private — the open source carve-out does not apply here + +The root file notes that documentation under `content/develop/` legitimately links to +source code and documents implementation internals, because the products documented +there are open source. **Feature Form is not.** Its source repository is private, so a +file path, repository URL, or "see the implementation" pointer is a dead end for every +reader of these pages. + +These pages currently contain no source links. Do not add one. + +Where a statement was only defensible because it cited code, it either stands on its own +as documented behavior or it comes out. "Check the source for the supported providers", +in any phrasing, means the page has a real gap. Flag it rather than shipping it. + +Published pages carry no audit trail. Strip verification notes, "verified against" +lines, source lists, and freshness dates. + +## Product names + +| Use | Not | Note | +| --- | --- | --- | +| Redis Feature Form | Featureform, Feature form | First mention on a page. | +| Feature Form | Featureform, FF | Every later mention on that page. | +| feature platform | feature store | What the product is. The pages use "feature platform"; "feature store" appears nowhere in them. | + +**"Featureform" as one word is a code identifier, never prose.** It is correct in the +Python package (`import featureform as ff`), in a module path, and in a type name such as +`ff.FeatureformError`. It is wrong in a sentence. + +The command-line tool is `ff`. Use the literal in commands, and never as an abbreviation +for the product in prose. + +## Resource vocabulary + +`concepts.md` defines the resource types and is the canonical source for them. Do not +restate those definitions on another page — link to it. The distinctions below are the +ones most often gotten wrong. + +- **Features and labels have the same shape and different jobs.** A feature is model + input read at inference time. A label is the target value a model is trained to + predict, and feeds offline training rather than online serving. They are not + interchangeable. +- **A dataset registers data that already exists** in an offline store. A + **transformation** produces a new dataset from existing ones. Neither is a "source" — + that word is not a resource type here. +- **A feature view is the only graph resource downstream applications read from.** + Applications do not query features directly. +- **A workspace is the isolation boundary.** Nothing is shared between workspaces. Never + describe a resource as shared, global, or deployment-wide unless the page says so. + +Provider **roles** are literal values — `offline-store`, `online-store`, `compute`, +`streaming` — and are not reworded or capitalized to fit a sentence. A provider fills one +or more roles; it is not "an offline store" in prose where the role name is meant. + +## Materialization is described abstractly — never expose the storage layout + +Feature Form materializes feature values into an online store, typically Redis. Describe +what materialization achieves — that values are populated and available to serve — and +stop there. + +**Never document how those values are laid out in Redis.** No key formats, no key naming +schemes, no hash field names, no reserved metadata fields, no internal encodings. This is +a deliberate decision, not an omission to helpfully fill in: the layout is internal, it +changes without notice, and a reader who builds against it builds on sand. + +The same holds for the planner and the task DAG. What a change causes is documentable; +how the work is scheduled and executed internally is not. + +## Do not weaken the credential claim + +These pages state that Feature Form never stores credentials in any form — not +plaintext, not hashed, not encrypted — and that a provider configuration carries only a +reference to a separately registered secret backend. + +That is a security claim about the product. Do not soften it, qualify it, or restate it +in looser words while editing nearby prose. If something appears to contradict it, flag +it; do not resolve it in the text. + +Examples never contain a real credential, host, or account identifier. A secret reference +in an example is a reference, such as `env:PG_PASSWORD` — not a value. + +## Document current behavior only + +Do not foreshadow planned support, future feature expansions, or roadmap items — even +when a specification, an internal document, or a subject-matter expert mentions them. +Planned work slips, changes shape, or gets cut, and removing a promise from a published +page is visible to customers. + +- Wrong: "Support for additional providers is planned." +- Wrong: "This provider is expected to gain streaming support." +- Right: state which providers and roles are documented today, and stop. + +**Carve-out — deprecation and removal notices are correct and expected.** The rule bans +promising something the reader will *gain*, not telling them what is going away. +Customers need lead time to migrate, and a warning is sometimes published ahead of the +removal itself to give them that time. + +The test: does the sentence tell the reader they will gain something, or lose something? +Gains are out. Losses are in. + +## Do not publish ahead of customer availability + +Content describing a feature does not go live until customers can use it. The gate is +availability to customers — not that the code merged, and not that the capability exists +in an internal build. A feature that is cut or deferred takes its documentation with it: +remove the content rather than softening it into a promise. + +Drafting ahead is normal. Draft, verify, open the pull request, and hold it. + +## Flag rather than decide + +- **A provider, role, or resource field cannot be confirmed** against the documented + behavior. Never infer a supported provider or an accepted argument. +- **An example would need a credential, a real endpoint, or infrastructure detail** to + work as written. +- **Internal material contradicts a published page.** The internal version does not + automatically win — it may describe unreleased behavior or an internal rename. +- **A term appears that this file and `concepts.md` do not cover.** diff --git a/content/operate/featureform/CLAUDE.md b/content/operate/featureform/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/content/operate/featureform/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 462f9ae5415a59ab4f1458be28b8b3dab2182e55 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 17 Aug 2026 15:59:44 -0500 Subject: [PATCH 4/4] absolute file path for ff --- content/develop/ai/featureform/AGENTS.md | 9 +++++---- content/operate/featureform/AGENTS.md | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/content/develop/ai/featureform/AGENTS.md b/content/develop/ai/featureform/AGENTS.md index 5df382f733..1730f6aafd 100644 --- a/content/develop/ai/featureform/AGENTS.md +++ b/content/develop/ai/featureform/AGENTS.md @@ -48,9 +48,10 @@ for the product in prose. ## Resource vocabulary -`concepts.md` defines the resource types and is the canonical source for them. Do not -restate those definitions on another page — link to it. The distinctions below are the -ones most often gotten wrong. +The concepts page at `content/develop/ai/featureform/concepts.md` defines the resource +types and is the canonical source for them. Do not restate those definitions on another +page — link to it with `{{< relref "/develop/ai/featureform/concepts" >}}`. The +distinctions below are the ones most often gotten wrong. - **Features and labels have the same shape and different jobs.** A feature is model input read at inference time. A label is the target value a model is trained to @@ -131,4 +132,4 @@ Drafting ahead is normal. Draft, verify, open the pull request, and hold it. work as written. - **Internal material contradicts a published page.** The internal version does not automatically win — it may describe unreleased behavior or an internal rename. -- **A term appears that this file and `concepts.md` do not cover.** +- **A term appears that neither this file nor the concepts page covers.** diff --git a/content/operate/featureform/AGENTS.md b/content/operate/featureform/AGENTS.md index 5df382f733..1730f6aafd 100644 --- a/content/operate/featureform/AGENTS.md +++ b/content/operate/featureform/AGENTS.md @@ -48,9 +48,10 @@ for the product in prose. ## Resource vocabulary -`concepts.md` defines the resource types and is the canonical source for them. Do not -restate those definitions on another page — link to it. The distinctions below are the -ones most often gotten wrong. +The concepts page at `content/develop/ai/featureform/concepts.md` defines the resource +types and is the canonical source for them. Do not restate those definitions on another +page — link to it with `{{< relref "/develop/ai/featureform/concepts" >}}`. The +distinctions below are the ones most often gotten wrong. - **Features and labels have the same shape and different jobs.** A feature is model input read at inference time. A label is the target value a model is trained to @@ -131,4 +132,4 @@ Drafting ahead is normal. Draft, verify, open the pull request, and hold it. work as written. - **Internal material contradicts a published page.** The internal version does not automatically win — it may describe unreleased behavior or an internal rename. -- **A term appears that this file and `concepts.md` do not cover.** +- **A term appears that neither this file nor the concepts page covers.**