feat: resolve GitHub repository files through local Git checkouts

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opinionated TS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,19 +1,42 @@
 # write-once-github
 
-Official GitHub repository integration for [write-once](https://github.com/opinionated-ts/write-once).
+[![npm version](https://img.shields.io/npm/v/write-once-github)](https://www.npmjs.com/package/write-once-github)
+[![npm downloads](https://img.shields.io/npm/dm/write-once-github)](https://www.npmjs.com/package/write-once-github)
+[![CI](https://img.shields.io/github/actions/workflow/status/opinionated-ts/write-once-github/check-and-release.yml?label=CI)](https://github.com/opinionated-ts/write-once-github/actions/workflows/check-and-release.yml)
+[![License](https://img.shields.io/github/license/opinionated-ts/write-once-github)](https://github.com/opinionated-ts/write-once-github/blob/main/LICENSE)
 
-This package is under development. Its repository reference syntax, ref resolution behavior, and public API will be documented here as the integration is implemented.
+A [Write Once](https://github.com/opinionated-ts/write-once) plugin for resolving files from GitHub repositories through local Git checkouts.
 
-## Development
+## Install
 
 ```sh
-bun install
-bun test
-bun check
-bun build
+bun add -d write-once write-once-github
 ```
 
-## Related projects
+Register the plugin in `write-once.config.ts`:
 
-- [write-once](https://github.com/opinionated-ts/write-once) — core resource preparation, resolution, and content extraction pipeline.
-- [Opinionated TS](https://github.com/opinionated-ts) — the ecosystem this package belongs to.
+```ts
+import { defineConfig } from "write-once";
+import { githubPlugin } from "write-once-github";
+
+export default defineConfig({ plugins: [githubPlugin] });
+```
+
+## References
+
+```text
+repo:owner/repository/path/to/file.ts
+repo:owner/repository@develop/path/to/file.ts
+repo:owner/repository@feature/nested/path/to/file.ts
+```
+
+Without `@ref`, the repository's default branch is used. Explicit references can be branches, tags, or commit SHAs. Branches take precedence over same-named tags.
+
+The GitHub plugin only resolves the repository file. Whole-file, named-fragment, and range selection are handled by Write Once.
+
+## Authentication
+
+- Public repositories require no credentials.
+- Private repositories use `GITHUB_TOKEN` from the process environment.
+- The token should have access to the repository with `Contents: Read-only` and `Metadata: Read-only` permissions.
+- `GITHUB_GIT_PROTOCOL=ssh` uses SSH instead of HTTPS when SSH credentials are already configured.

SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest released version of `write-once`. Upgrade to the latest version before reporting an issue when possible.
+
+| Version        | Supported |
+| -------------- | --------- |
+| Latest release | Yes       |
+| Older releases | No        |
+
+## Reporting a Vulnerability
+
+Please report suspected security vulnerabilities privately by emailing **[danhezcode@gmail.com](mailto:danhezcode@gmail.com)**. Do not disclose the issue publicly in a GitHub issue or discussion until it has been reviewed and a fix or mitigation can be coordinated.
+
+Include as much of the following information as possible:
+
+- The affected version and environment.
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce the issue or a proof of concept.
+- Any suggested mitigation, if known.
+
+You should receive an acknowledgment within 7 days. We will investigate the report, assess its impact, and coordinate next steps with you where possible. Please allow time for a fix or mitigation before sharing details publicly.
+
+## Scope
+
+Reports are especially relevant to unintended file access or modification, unsafe handling of fragment markers or configuration, and other behavior that could compromise a user's project or data. Do not include real secrets or sensitive data in reports; use sanitized examples where possible.