Documentation agent optimisation. Closes #20#21
Open
binaek wants to merge 23 commits into
Open
Conversation
…ness This commit introduces significant updates to the Sentrie documentation, enhancing the organization and accuracy of information across various sections. **Key Changes:** - **Getting Started Section**: - Replaced outdated entries with new content, including an introduction to Sentrie and a quick start guide for installation and policy evaluation. - **Language Concepts**: - Added comprehensive documentation on pattern matching, conditionals, and the type system, including shapes and constraints. - Introduced a new guide on policy composition, detailing the export and import of rules. - **Reference Documentation**: - Updated arithmetic and boolean operations documentation to reflect current syntax and examples. - Created a new CLI reference page detailing commands and their parameters. - **Extensibility**: - Added documentation for writing custom TypeScript modules, including syntax and usage examples. - **Deployment Operations**: - Introduced new pages for running Sentrie as a service and CLI reference, detailing commands and expected behaviors. **Benefits:** - Improved clarity and usability of documentation for new and existing users. - Enhanced organization of content for easier navigation and understanding. - Comprehensive coverage of new features and concepts introduced in recent updates. ## Testing - Documentation reviewed for accuracy and consistency. - All new pages and updates verified for correct rendering and functionality. ## Dependencies - None - documentation-only changes.
28 tasks
🚀 Preview DeploymentA preview of this PR has been deployed to https://sentrie-pr-21.surge.sh: 🔗 View Preview at https://sentrie-pr-21.surge.sh This preview will be automatically removed when the PR is merged or closed. |
This commit improves the Sentrie documentation by refining formatting, enhancing descriptions, and ensuring consistency in terminology. **Key Changes:** - **Parameter Tables**: Standardized formatting for parameter tables across various documentation files for better readability. - **Return Descriptions**: Updated return descriptions to use consistent punctuation, changing from "—" to "-" for clarity. - **Content Refinements**: Made minor adjustments to text for improved flow and clarity, including removing unnecessary line breaks and ensuring concise explanations. **Benefits:** - Improved readability and user experience for documentation. - Consistent formatting enhances the professional appearance of the documentation. ## Testing - Documentation reviewed for accuracy and consistency. - All changes verified for correct rendering and functionality.
…for consistency across multiple files
…ion, writing your first policy, and running policies
…perations with comprehensive details and examples
…ency across multiple sections
…t package manager and streamline build process
…ent variable for deployment verification
…, ensuring accurate representation of behavior in the language.
…ny`, `all`, `count`, `distinct`, `reduce`, and `filter`. Clarify usage of loop variables and recursive value comparison in membership operations for maps.
…ic-discovery-llmo
…ic-discovery-llmo
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.
If merged, this pull request will overhaul the sentrie.sh documentation to a brutalist, structured, agent-optimized format with a universal page template, rewritten reference and concept pages, and six-domain navigation (Getting Started, Language Concepts, Language Reference, TypeScript Modules, Extensibility, Deployment & Operations).
Summary
This PR implements the Documentation Agent Optimization plan: machine-readable docs with high signal-to-noise, strict schemas, explicit types and constraints, and no marketing fluff.
What changed
docs-template.mdat repo root (exact Appendix format). All new/rewritten pages follow it (Syntax → Parameters → Examples → Behavior & Constraints).introduction.md(determinism, core philosophy),quick-start.md(install + first evaluation). Content from what-is-sentrie, why-sentrie, installation, writing-your-first-policy, running-your-policy preserved and restructured. Homebrew installation removed from installation and quick-start (not stable yet); install script is the documented method on macOS.type-system-shapes.md,policy-composition.md(from exporting-and-importing-rules),pattern-matching-conditionals.md. Focus on “how it works.”reference/typescript_modules/with index + 12sentrie/*.md). Each page restructured per template; “Behavior & Constraints” added where missing. TypeScript Modules is a top-level sidebar section (brought up from under Reference).extensibility/writing-custom-typescript-modules.md(from reference/using-typescript). Paths,usesyntax,@local, aliasing preserved.deployment-operations/cli-reference.md,deployment-operations/running-as-service.mdwith strict HTTP API and error format. No new dependencies.astro.config.mjsreplaced with six domains. Homepage hero and six feature cards updated to route to the new sections (Quick Start → quick-start, Type-Safe Inputs → types-and-values, Expression Language → arithmetic-operations, Composable Policies → policy-composition, TypeScript Integration → typescript_modules, Run as a Service → running-as-service).Why
Page length
js.md) retain full content with template sections added; no splits were required for current page set.Review focus
/referencereads as a strict dictionary (no tutorial tone).getting-started/installation,reference/exporting-and-importing-rules,cli-reference/) still exist and still build; only the sidebar and homepage point at the new structure. Redirects or removal of old pages can be a follow-up.Reviewer Q&A
reference/typescript_modules/; they are restructured to the template and appear under the top-level “TypeScript Modules” sidebar group.Testing
yarn buildpasses (64 pages built).descriptioncontaining a colon (YAML-quoted) so the content collection parses.Dependencies