jentic · frankkilcommins · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,61 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to providing a welcoming, safe, and equitable environment for all participants, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Expected Behaviour
+
+Community members are expected to:
+
+- Respect the purpose and goals of this project
+- Engage with others kindly, honestly, and constructively
+- Accept differing viewpoints and experiences
+- Give and receive constructive feedback gracefully
+- Take responsibility for mistakes and work to repair any harm caused
+- Focus on what's best for the overall community
+
+## Unacceptable Behaviour
+
+The following behaviors are not tolerated:
+
+- Harassment, intimidation, or boundary violations of any kind
+- Personal attacks, insults, or derogatory comments
+- Stereotyping or discriminatory language or imagery
+- Sexualized language, imagery, or unwelcome sexual attention
+- Publishing others' private information without explicit consent
+- Threats of violence or encouraging violence toward others
+- Impersonation or misrepresenting identity or affiliation
+- Failing to properly attribute sources or credit others' work
+- Any conduct reasonably considered inappropriate in a professional setting
+
+## Reporting
+
+If you experience or witness unacceptable behaviour, please report it to **[hello@jentic.com](hello@jentic.com)**. All reports will be handled confidentially.
+
+Reports should include:
+
+- Your contact information
+- Description of the incident (what happened, when, where)
+- Any supporting documentation or evidence
+- Names of witnesses, if any
+
+## Enforcement
+
+Violations will be addressed promptly and fairly. Consequences depend on the severity and frequency of violations:
+
+1. **Warning**: Private written notice explaining the violation and expected corrective action
+2. **Temporary restriction**: Limited participation in community spaces for a defined period
+3. **Permanent ban**: Removal from all community spaces (reserved for severe or repeated violations)
+
+## Scope
+
+This Code of Conduct applies to all community spaces including GitHub repositories, discussions, issues, pull requests, and any official community channels. It also applies when representing the project in public spaces.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 3.0.
+
+## Questions
+
+For questions about this Code of Conduct, contact **[hello@jentic.com](hello@jentic.com)**.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,92 @@
+# Contributing to the Jentic API AI-Readiness Framework
+
+We welcome contributions from the community. Whether you're reporting bugs, suggesting improvements, or submitting changes, your input helps strengthen this framework for everyone.
+
+## How to Contribute
+
+### Reporting Issues
+
+Found a problem or have a suggestion? Open an issue on GitHub:
+
+- **Bug reports**: Describe the issue, expected behaviour, and steps to reproduce
+- **Feature requests**: Explain the use case and why it would benefit the framework
+- **Documentation improvements**: Point out gaps, errors, or areas needing clarification
+
+Before opening a new issue, search existing issues to avoid duplicates.
+
+### Contributing Code
+
+We accept pull requests for bug fixes, documentation improvements, and new features. For substantial changes, open an issue first to discuss your approach before investing significant time.
+
+**Types of contributions:**
+
+- **Documentation**: Clarifications, corrections, and examples are always welcome
+- **Bug fixes**: If the fix is straightforward, submit a PR directly. For complex issues, discuss in an issue first
+- **New features**: Must be discussed in an issue before PR submission to ensure alignment with framework goals
+
+### Pull Request Process
+
+1. **Create an issue** describing the problem or feature (unless it's a trivial fix)
+2. **Fork the repository** and create a branch from `main`
+3. **Make your changes** with clear, focused commits
+4. **Test your changes** to ensure they work as intended
+5. **Submit a pull request** referencing the related issue
+6. **Respond to feedback** during the review process
+
+Keep PRs small and focused. Large changes should be broken into multiple PRs when possible.
+
+## Coding Guidelines
+
+### Branch Naming
+
+Use descriptive branch names with prefixes:
+
+- `feature/` for new features
+- `fix/` for bug fixes
+
+Optionally include the issue number: `fix/123-typo-in-spec`
+
+### Commit Messages
+
+Write clear, atomic commits that represent logical units of change:
+
+- Use present tense, imperative mood: "Add scoring algorithm" not "Added" or "Adds"
+- Keep subject lines under 69 characters
+- Reference issues using `Refs #<issue-number>` in the commit body
+- Follow [Conventional Commits](https://www.conventionalcommits.org/) format when possible
+
+**Examples:**
+
+```text
+docs: fix typo in specification section 4.2
+
+Refs #42
+```
+
+```text
+feat: add usability scoring dimension
+
+Implements new scoring logic for agent usability metrics.
+
+Refs #127
+```
+
+### Merging
+
+Maintainers will typically use "Squash and merge" to keep the commit history clean. The squashed commit will follow Conventional Commits format.
+
+## Code of Conduct
+
+All contributors must follow our [Code of Conduct](CODE_OF_CONDUCT.md). We're committed to providing a welcoming, safe, and respectful environment for everyone.
+
+## Questions?
+
+- Open a [GitHub Discussion](../../discussions) for general questions
+- Comment on existing issues for specific topics
+- Reach out to maintainers listed in [MAINTAINERS.md](MAINTAINERS.md)
+
+## Recognition
+
+Contributors are recognized in the project history through commit attribution and acknowledgment in release notes.
+
+Thank you for contributing to the Jentic API AI-Readiness Framework!
diff --git a/README.md b/README.md
@@ -1,44 +1,60 @@
 # Jentic API AI-Readiness Framework (JAIRF)
 
-_Just heard of API AI-Readiness and not sure where to start? See the specification in this repository._
+A syntactically valid OpenAPI description doesn't guarantee your API is ready for AI systems. Validity ensures conformance to the spec's grammar—but AI agents need APIs that express intent clearly and can be reasoned over safely by machines.
 
-This repo contains the:
+This repository contains the **Jentic API AI-Readiness Framework (JAIRF)**: a standards-aligned specification for evaluating how well APIs serve AI agents across six critical dimensions.
 
-- **API AI-Readiness Framework (JAIRF) specification**
-- **Reference scoring model and algorithms**
-- **Supporting documentation, terminology, and guidance for implementers**
+**What's included:**
 
-The framework defines a standards-aligned model for evaluating the AI-readiness of APIs across six key dimensions:
+- **Framework specification** defining evaluation criteria and scoring methodology
+- **Reference scoring algorithms** for consistent, automated assessment
+- **Guidance for implementers** to improve API AI-readiness
 
-1. **Foundational Compliance**  
-2. **Developer Experience & Tooling Compatibility**  
-3. **AI-Readiness & Agent Experience**  
-4. **Agent Usability & Orchestration**  
-5. **Security & Governance**  
-6. **AI Discoverability**
+## The Six Dimensions
 
-JAIRF is published as a Markdown specification designed for adoption, extension, and future standardisation.
+JAIRF evaluates APIs across these areas:
 
-## Reference Implementation
+1. **Foundational Compliance** – Structural validity and standards conformance
+2. **Developer Experience & Tooling Compatibility** – Documentation quality and tooling support
+3. **AI-Readiness & Agent Experience** – Semantic clarity and context sufficiency for AI systems
+4. **Agent Usability & Orchestration** – Safe, predictable multi-step operations
+5. **Security & Governance** – Authentication, authorization, and trust mechanisms
+6. **AI Discoverability** – How easily AI systems can find and understand your API
 
-Head over to [Jentic API AI-Readiness Scoring](https://jentic.com/api-score-preview) page, to see AI-readiness scoring in action.
+Small, targeted improvements in these areas produce outsized gains for both human developers and AI agents.
+
+## Score Your APIs
+
+See AI-readiness scoring in action at [jentic.com/scorecard](https://jentic.com/scorecard). Upload your OpenAPI specification and receive an instant assessment across all six dimensions.
+
+![API AI-Readiness Scorecard](assets/scorecard-preview.jpg)
+
+Sample Top-level Scorecard:
+
+![Sample Scorecard](assets/sample-score-card-header.png)
 
 ## Publishing
 
 Changes to `docs/specification/spec.md` on the `main` branch automatically publish to [jentic-docs](https://github.com/jentic/jentic-docs) via GitHub Actions. The workflow creates a PR with the updated specification.
 
-**Requirements**: Repository secret `JENTIC_DOCS_TOKEN` (GitHub PAT with `repo` scope).
+You can view the published docs at [https://docs.jentic.com](https://docs.jentic.com/reference/api-readiness-framework/overview/).
 
-**Local testing**: `./scripts/publish-to-docs.sh --dry-run test-sha dummy-token`
 
 ## Maintainers
 
 See [MAINTAINERS.md](./MAINTAINERS.md).
 
 ## Contributing
 
-A `CONTRIBUTING.md` guide will be added shortly.
-Issues, discussions, and pull requests are welcome.
+We welcome contributions from the community. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting issues, submitting pull requests, and coding standards.
+
+All contributors must follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Building Upon the Jentic API AI-Readiness Framework
+
+If you build tools, extensions, or derived works based on this framework, please credit the Jentic API AI-Readiness Framework (JAIRF) and link back to this repository. This helps maintain the framework's visibility, accuracy, and supports the broader API and AI community.
+
+The framework is licensed under [Apache License 2.0](LICENSE), which permits commercial and non-commercial use with proper attribution.
 
 ## License
 

diff --git a/assets/sample-score-card-header.png b/assets/sample-score-card-header.png
diff --git a/assets/scorecard-preview.jpg b/assets/scorecard-preview.jpg
diff --git a/docs/publishing/overview-template.md b/docs/publishing/overview-template.md
@@ -96,12 +96,19 @@ The framework works with OpenAPI 3.x and 2.x specifications. It's implementation
 ## Related Resources
 
 - **[Full Specification](specification.md)** — Complete technical specification with normative requirements
+- **[Framework Repository](https://github.com/jentic/api-ai-readiness-framework)** — full source specification, contribution guidelines, and issue tracking
 - **[Jentic Public APIs](https://github.com/jentic/jentic-public-apis)** — Collection of scored API specifications demonstrating the framework in practice
 - **Blog Posts**:
   - [Why Most APIs Fail in AI Systems and How to Fix It](https://thenewstack.io/why-most-apis-fail-in-ai-systems-and-how-to-fix-it/) (The New Stack)
   - [Is Your OpenAPI AI-Ready?](https://jentic.com/blog/is-your-open-api-ai-ready) (Jentic)
   - [Scoring APIs for AI](https://jentic.com/blog/scoring-apis-for-ai) (Jentic)
 
+## Contributing
+
+This framework is open source and welcomes community contributions. Whether you're reporting issues, suggesting improvements, or building upon the specification, your input helps strengthen the framework for everyone.
+
+Visit the [GitHub repository](https://github.com/jentic/api-ai-readiness-framework) to get started. See [CONTRIBUTING.md](https://github.com/jentic/api-ai-readiness-framework/blob/main/CONTRIBUTING.md) for guidelines.
+
 ## Specification Metadata
 
 - **Version**: {{VERSION}}