Add documentation for public release readiness, including issue and p…

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Report a reproducible XCSKit problem
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Description
+
+Describe the problem clearly.
+
+## Reproduction
+
+Steps or a minimal Swift snippet:
+
+```swift
+
+```
+
+Minimal `.xcstrings` input if relevant:
+
+```json
+
+```
+
+## Expected Behavior
+
+What did you expect to happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Environment
+
+- XCSKit version or commit:
+- Swift version:
+- Xcode version:
+- OS:
+
+## Additional Context
+
+Add logs, stack traces, or links when useful.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What user or developer problem would this solve?
+
+## Proposed Solution
+
+Describe the API, behavior, or documentation change you would like.
+
+## Alternatives Considered
+
+What other approaches did you consider?
+
+## Scope
+
+- Affected module or modules:
+- Does this require an SRS update? Yes / No / Unsure
+- Does this require new tests? Yes / No / Unsure
+
+## Additional Context
+
+Add examples, catalog shapes, or links when useful.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+- 
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Documentation
+- [ ] Tests
+- [ ] CI or repository maintenance
+
+## Requirements and Tests
+
+- [ ] I updated `docs/SRS.md` if committed behavior changed.
+- [ ] I added or updated requirement-level tests when applicable.
+- [ ] `swift build` passes locally.
+- [ ] `swift test` passes locally.
+
+## Notes
+
+Include any compatibility notes, migration details, or follow-up work.

CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to XCSKit are documented in this file.
+
+The project follows semantic versioning while it is pre-1.0. Public API changes may still occur before a stable 1.0 baseline.
+
+## Unreleased
+
+### Added
+
+- MIT License file.
+- Public release readiness documentation, including contribution, security, conduct, changelog, issue template, and pull request template guidance.
+- README installation instructions, requirements, license, and public API status notes.
+
+### Changed
+
+- Swift CI now runs on pull requests, pushes to `main`, and manual dispatches.
+- SRS document control now uses public-facing audience and status language.
+
+## 0.3.1
+
+### Fixed
+
+- Translation progress calculations and related documentation updates.
+
+## 0.3.0
+
+### Changed
+
+- Adjusted Swift CI trigger behavior.
+
+## 0.2.2
+
+### Fixed
+
+- Fixed translator patch generation behavior.
+
+## 0.2.1
+
+### Changed
+
+- Moved parser and shared model implementation toward `Codable`-based decoding.
+
+## 0.2.0
+
+### Added
+
+- Added the XCSAnalytics module.
+
+## 0.1.0
+
+### Added
+
+- Initial tagged baseline for XCSKit.

CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+XCSKit aims to be a respectful, practical, and welcoming project for people working on localization tooling.
+
+## Expected Behavior
+
+- Be respectful and constructive in issues, pull requests, and reviews.
+- Assume good intent, especially when discussing bugs or design tradeoffs.
+- Keep feedback focused on the work and its impact on users.
+- Make room for different experience levels with Swift, localization, and open source.
+
+## Unacceptable Behavior
+
+- Harassment, threats, personal attacks, or sustained disruption.
+- Discriminatory language or conduct.
+- Publishing private information without permission.
+- Sharing sensitive security details publicly before a coordinated disclosure.
+
+## Enforcement
+
+Project maintainers may moderate, edit, or remove comments and may restrict participation when behavior harms the project or its contributors.
+
+If you need to report conduct concerns, contact the maintainer privately with relevant context and links.

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to XCSKit
+
+Thanks for taking the time to improve XCSKit. This project is a Swift Package for parsing, validating, translating, writing, and analyzing Apple's `.xcstrings` catalogs.
+
+## Development Setup
+
+Requirements:
+
+- Swift 6.3
+- Swift Package Manager
+- macOS for the currently verified CI environment
+
+From the repository root, use:
+
+```bash
+swift build
+swift test
+```
+
+## Branches and Pull Requests
+
+- Create focused branches such as `docs/public-release-readiness`, `fix/parser-error-paths`, or `feature/validator-findings`.
+- Keep pull requests scoped to one behavior change, documentation change, or release task.
+- Include tests for behavior changes and update documentation when public APIs or requirements change.
+- Run `swift build` and `swift test` before opening or updating a pull request.
+
+## Requirements and Tests
+
+The public requirements baseline lives in [docs/SRS.md](docs/SRS.md). Requirement-level tests use matching IDs:
+
+- Requirement `VAL-004` maps to `Tests/XCSKitTests/VAL_004.swift`.
+- Requirement `TRN-003` maps to `Tests/XCSKitTests/TRN_003.swift`.
+- Requirement `WRT-005` maps to `Tests/XCSKitTests/WRT_005.swift`.
+
+When adding or changing committed requirements, update both the SRS requirement text and the requirement-to-test mapping table.
+
+## Style Notes
+
+- Prefer small, explicit public APIs with descriptive type and method names.
+- Keep parser, validator, translator, writer, analytics, and core-model responsibilities separated.
+- Avoid adding runtime package dependencies unless the project explicitly decides to expand scope.
+- Preserve `.xcstrings` values and placeholder tokens exactly unless a documented writer operation intentionally changes them.
+
+## Reporting Issues
+
+For bugs, include the Swift version, OS, package version or commit, a minimal catalog sample when possible, expected behavior, and actual behavior.
+
+For sensitive security reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.

README.md

@@ -2,7 +2,43 @@
 
 XCSKit is a Swift Package for working with Apple's `.xcstrings` string catalog files through a layered set of modules.
 
-The repository includes a working parser implementation, a representative sample catalog, an automated test suite, and a formal software requirements specification that now tracks the next v2 increment.
+The repository includes a working parser implementation, a representative sample catalog, an automated test suite, and a public software requirements specification that tracks implemented behavior and near-term roadmap items.
+
+## Installation
+
+Add XCSKit to a Swift Package Manager project with the repository URL:
+
+```swift
+dependencies: [
+	.package(url: "https://github.com/chatoutsidis/XCSKit.git", from: "0.3.1")
+]
+```
+
+Then add whichever product you need to your target dependencies:
+
+```swift
+.target(
+	name: "YourTarget",
+	dependencies: [
+		.product(name: "XCSParser", package: "XCSKit"),
+		.product(name: "XCSValidator", package: "XCSKit"),
+		.product(name: "XCSWriter", package: "XCSKit")
+	]
+)
+```
+
+In Xcode, use **File > Add Package Dependencies...**, enter the repository URL, and select the products your app or tool imports. Use `XCSKit` when you want the umbrella import, or choose individual products for narrower module boundaries.
+
+## Requirements
+
+| Requirement             | Current Support                |
+|-------------------------|--------------------------------|
+| Swift tools             | 6.3                            |
+| Package manager         | Swift Package Manager          |
+| Runtime dependencies    | None                           |
+| Verified CI environment | macOS 15 runner with Swift 6.3 |
+
+The package is Foundation-based and intended for local tooling, server-side utilities, and Apple-platform build workflows. Broader platform minimums should be treated as uncommitted until they are added to the package manifest and CI matrix.
 
 ## Goals
 
@@ -264,14 +300,22 @@ Continuous integration:
 - `XCSWriter` API guide: [docs/modules/XCSWriter.md](docs/modules/XCSWriter.md)
 - `XCSAnalytics` API guide: [docs/modules/XCSAnalytics.md](docs/modules/XCSAnalytics.md)
 - `XCSKit` umbrella guide: [docs/modules/XCSKit.md](docs/modules/XCSKit.md)
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Release notes: [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+XCSKit is available under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## Status
 
 Current repository status:
 
 - Package manifest is present in [Package.swift](Package.swift) and now exposes parser, core, validator, translator, and writer modules.
 - Parser implementation supports core `.xcstrings` parsing, typed lookup helpers, and forward-compatible extraction-state metadata.
-- Validation, translation orchestration, and writing are implemented as separate layers over the shared catalog model.
-- The checked-in tests cover parsing, validation, placeholder preservation, representative variant behavior, and the new separation layers.
+- Validation, translation orchestration, writing, and analytics are implemented as separate layers over the shared catalog model.
+- The checked-in tests cover parsing, validation, placeholder preservation, representative variant behavior, translation workflows, writer behavior, analytics, and non-functional requirements.
+- The public API is still pre-1.0. Minor releases may refine API names or module boundaries before a stable 1.0 baseline.
 
 If you are contributing implementation work, start with [docs/SRS.md](docs/SRS.md). It defines the committed v1 requirements, validation behavior, non-functional constraints, and planned verification coverage.

SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+XCSKit is currently pre-1.0. Security fixes are expected to land on the default branch first and be included in the next tagged release.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a vulnerability report.
+
+Use GitHub private vulnerability reporting for this repository if it is enabled. If private reporting is not yet available, contact the maintainer through a private channel first and include only enough information to establish contact.
+
+Helpful report details include:
+
+- Affected XCSKit version or commit
+- Swift version and operating system
+- Minimal `.xcstrings` input or API sequence needed to reproduce the issue
+- Expected and observed impact
+- Whether the issue is already public
+
+The maintainer will acknowledge reports as soon as practical, investigate reproducibility and impact, and coordinate disclosure timing before public details are published.

docs/SRS.md

@@ -4,16 +4,16 @@
 
 - Product: XCSKit
 - Type: Swift Package library
-- Version: Draft v2.2
-- Status: Working draft for implementation and verification
-- Date: 2026-04-17
-- Intended audience: Internal engineering
+- Version: v2.2 public baseline
+- Status: Public requirements baseline for implemented behavior and near-term roadmap
+- Date: 2026-06-10
+- Intended audience: Developers and contributors
 
 ## 2. Purpose and Scope
 
 XCSKit is a Swift Package for working with Apple's `.xcstrings` string catalog files through a layered set of modules. The package centers on shared typed domain models and currently includes a parse-only parser, a non-mutating validator, a provider-driven translator, a writer for serialization and patch-oriented persistence, and a read-only analytics module for reporting and statistics. This SRS defines the committed requirements for the parser baseline and the implemented validator, translator, writer, and analytics capabilities.
 
-As of the date of this revision, the repository contains a working implementation of the parser baseline, initial validator/translator/writer layers, automated tests for the committed behavior, and a representative sample catalog. Accordingly, this document serves both as a description of committed behavior and as the requirements baseline for the next increment.
+As of the date of this revision, the repository contains a working implementation of the parser baseline, validator, translator, writer, and analytics layers, automated tests for the committed behavior, and a representative sample catalog. Accordingly, this document serves both as a public description of committed behavior and as the requirements baseline for the next increment.
 
 ## 3. Product Overview