@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/AUTHORING.md

@@ -0,0 +1,269 @@
+# Authoring command reference
+
+Detailed CLI and library contracts for project inspection, isolated validation, review, and preview. For installation and a first project, start with the [package README](README.md).
+
+## Project and reference tools
+
+These provider-free commands inspect an existing project without selecting a page:
+
+```sh
+shoalrun docs project --config docs.config.yaml
+shoalrun docs project --section guidance --config docs.config.yaml
+shoalrun docs project --section configuration --config docs.config.yaml
+shoalrun docs project --query "installation" --config docs.config.yaml
+shoalrun docs project --id guide.install --section relationships --config docs.config.yaml
+shoalrun docs source AGENTS.md --config docs.config.yaml
+shoalrun docs search "Steps" --json
+shoalrun docs read guide.component.steps --json
+```
+
+`--config` defaults to the nearest `docs.config.yaml` in the current directory or
+its ancestors. The project root is the configuration directory. Search/read reuse
+the bundled documentation and their existing token budgets/publication filters;
+they need no project or model key. The Steps reference contains exact MDX,
+required attributes, nesting, accessibility and HTML/Markdown semantics. Use
+`guide.frontmatter-reference` for metadata definitions, `guide.frontmatter` for
+authoring guidance, and `guide.templates` for page shapes. These references
+describe bundled framework behavior, not a consumer project's companion policy.
+
+`docs project` always returns JSON (`--json` is accepted). Its sections are:
+
+| Section | Entries |
+| --- | --- |
+| `pages` (default) | IDs, owning paths, SHA-256 source digests, resolved type/summary/slug, publication defaults, access and link-label aliases. Includes draft and untracked pages. |
+| `guidance` | Exact configured directives and guide/example locations, project/content and loaded configuration ancestors' `AGENTS.md` files, digests, source roles and directory scope. Read files with `docs source`. |
+| `configuration` | Leaf values for site, metadata defaults/enforcement/custom fields, publications, authoring source locations, audit, templates and search; each has its actual owning file/key/digest. |
+| `navigation`, `relationships` | Flattened entries/edges with actual configuration ownership. |
+| `templates` | Canonical scaffold definitions and project overrides, types, required fields and body locations. Page types remain extensible; this is a template catalogue, not a type whitelist. |
+| `findings` | Inspection errors, skipped symlinks and missing guidance/policy with severity, location when known and next action. |
+
+Choose at most one of `--id ID`, `--file PROJECT_RELATIVE_PATH`, or
+`--query TEXT` for pages/navigation/relationships. Topic matching is lexical over
+IDs, paths, titles, summaries, body text and aliases, using configured search
+synonyms. It returns ranked leads; it does not choose a page for the author.
+Navigation and relationship selectors use all matching IDs before pagination.
+An unknown selector returns an empty result.
+
+Project JSON schema version 1 has `kind: shoalrun-authoring-project`, `status`,
+`summary`, `section`, `entries`, `pagination`, `coverage` and `budget`.
+`summary` identifies the project/config digest, content directory, section counts,
+policy status, reference IDs and check availability. `coverage.validation` and
+check execution are `not-run`: inspection is not snapshot validation or a preview.
+Always inspect `summary.counts.findings` and read the findings section as needed.
+
+`--offset N` (default 0) and `--limit N` (default 20, range 1–100) page the
+selected section. `pagination.nextOffset` is null at the end. The serialized JSON
+fits `--max-tokens N` (default 8192, range 1024–100000, `cl100k_base`); a budget
+can reduce the number of entries. Follow the returned cursor, not the requested
+limit. An entry that cannot fit returns `invalid_input`; increase the budget or
+read its source passage. Pagination assumes an unchanged working tree. Inspection
+does not capture an atomic snapshot; rerun discovery after edits.
+
+`docs source FILE` returns schema version 1, `kind: shoalrun-authoring-source`,
+`status`, `file`, whole-file SHA-256 `digest`, `role`, `location`, `applicability`,
+`content`, `nextOffset` and `budget`. Paths must be project-relative and resolve
+inside the project; outside symlinks and traversal are rejected. Its `--offset`
+counts Unicode code points (not bytes), with a reported starting line. Its default
+budget is 4096 tokens (same range as project). Follow `nextOffset` to reconstruct
+long passages, including long lines. Check the digest between reads. External
+implementation roots are reported as configured locations; read them with the
+harness's own tools and permissions. Unconfigured sources are `unclassified`,
+never implicitly approved as technical evidence.
+
+Policy status is `missing` or `requires-interpretation`. Read all applicable
+policy/style/example sources. Opposing prose is retained for author review;
+the tool does not infer changelog, navigation or relationship obligations or
+silently choose between conflicting policies. Ancestor instructions outside the
+configuration directory remain the harness's responsibility. Configured audit
+settings are exposed, but inspection runs no shell checks.
+
+Both new commands exit 0 when inspection completes, even with findings. Request
+or execution failures exit 1 and emit JSON on stdout with `schemaVersion: 1`,
+`status: error`, and `error: { code, message }`. Codes are `invalid_input`,
+`unknown_source`, `unsafe_path`, `invalid_project` and `internal_error`.
+Findings use `code`, `severity` (`error`, `warning`, `review-needed`), optional
+`file`/`location`/`reference`, `explanation` and `nextAction`. A reference is a
+bundled documentation ID. Existing context/plan/apply and search/read retain
+their existing schemas and exit behavior.
+
+The public library entry point is `@shoalrun/cli/authoring`. API version 1 adds
+`inspectAuthoringProject(configFile, options)`,
+`readAuthoringSource(configFile, file, options)`, `projectToolSchemaVersion`,
+`projectSections`, `ProjectToolError`, `projectToolFailure`, and the existing
+`bundledDocumentation`, `searchDocumentation`, `getDocumentationPage` functions.
+New discovery capabilities are additive; checked plan/apply clients remain
+compatible. Library failures throw; CLI failures use the envelope above.
+
+The runtime package excludes compiled development tests.
+
+Run `npm run test:authoring-tools` from the repository root for the supported
+authoring contracts. Run `npm run authoring:package-check` for packed public
+CLI/library compatibility.
+
+After building, run `node framework/scripts/package-authoring-smoke.mjs --clean-install`
+from the repository root to install the tarball with fresh production dependencies
+and an empty npm cache. The check exercises both starters through the installed
+CLI and public library. This mode needs npm registry access. Provider credentials and
+`NODE_PATH` are omitted; browser downloads are disabled. It does not test diagrams
+or replace independent author trials. Without the flag, the check shares existing
+dependencies for an offline package compatibility check. Both modes remove their
+temporary consumers after completion.
+
+## Working-tree snapshot validation
+
+Capture a task baseline before editing when earlier local edits need to be
+distinguished from this task. Otherwise declare the changed files or IDs explicitly:
+
+```sh
+shoalrun docs baseline --out .shoalrun/task-baseline.json --config docs.config.yaml
+# Edit ordinary MDX/configuration files with the harness's native file tools.
+shoalrun docs validate --baseline .shoalrun/task-baseline.json --config docs.config.yaml
+shoalrun docs validate --file content/procedure.mdx --file config/nav.yaml --config docs.config.yaml
+shoalrun docs validate --id guide.install --config docs.config.yaml
+shoalrun docs validation-status /path/from/result/report.json
+```
+
+These commands always return JSON; `--json` is accepted. Configuration discovery
+works as for `docs project`. Baseline output is exclusive: choose a new filename
+for a new task. It records the **current working tree**, including earlier dirty
+and untracked files, rather than Git HEAD. It executes no checks. Its version-1
+`shoalrun-authoring-baseline` file contains project/config identity, input paths,
+SHA-256 digests, modes, external directory scope, exclusions and an integrity
+digest. A baseline from another project/configuration is rejected.
+
+`docs validate` requires either a baseline or explicit `--file`/`--id` selectors.
+Repeat file/ID flags for multiple changes; do not combine them with a baseline.
+Baseline comparison detects new, modified and deleted inputs, preserving earlier
+dirty files outside the task's change set. Sibling dependencies remain in baseline
+scope even after configuration stops referencing them. Explicit files describe
+the author's declared change set: absent paths declare deletions; unknown IDs
+fail (select broken/deleted pages by path). Without a baseline, prior file contents
+and creation history are unknown and reported as `declared`, not inferred from Git.
+
+Validation captures all regular project files within a 10000-file/256-MiB bound.
+It excludes `.git`, `node_modules`, `dist`, `site-dist`, `.vercel`, `.shoalrun`, `.private-archives`, `.private-evals`,
+`.aws`, `.ssh`, `.codex`, `.npmrc`, `.env` and `.env.*` entries and reports those
+exclusions. Source symlinks are rejected. Loaded configuration and supported local
+dependency paths, including sibling Walkthrough sources and page images, retain
+their relative layout within the project parent. Dependencies beyond that boundary
+or absolute local dependency paths are unsupported; a required excluded/uncaptured
+dependency cannot receive a passing report. External directory scopes are captured
+recursively. This is source capture, not a clean dependency installation.
+
+The compiler runs only on the temporary copy. Public pages and affected authored
+drafts are checked together. Configuration, source dependency and deletion changes
+conservatively affect every current authored page. Draft rendering uses an explicit
+compiler authoring option and retains authored/resolved access metadata, including
+enforced draft access. Unchanged, unselected drafts remain excluded from ordinary
+publication rendering. An affected page that matches no enabled publication is a
+located error, never a pass. Snapshot validation requires affected page IDs to
+match `[A-Za-z0-9][A-Za-z0-9._-]*`. This is the snapshot tool's stable-ID contract.
+Existing checked plan/apply keeps its prior behavior. Compiler checks cover metadata, identities/routes,
+components, document links, navigation and relationships. Local link/fragment checks
+read the actual HTML and Markdown; external URLs are not requested. Configured API
+example and focused-contract audits reuse the existing auditors.
+
+Configured `audit.tests` (including style/example commands) are **skipped** unless
+the harness explicitly runs `docs validate ... --run-checks` under its execution
+permissions. Commands run with argv and the captured project as their working
+directory, with `SHOALRUN_VALIDATION_SITE` and `SHOALRUN_VALIDATION_SNAPSHOT` set.
+These commands execute trusted project code. The harness must authorize them
+and ensure they operate on the capture rather than absolute live paths or external
+services. Declare sibling files/directories required by a check with optional
+`audit.tests[].inputs`, relative to the project configuration directory. Capture
+rejects missing files, symlinks, excluded locations and paths outside the project
+parent; directory additions/deletions participate in freshness. Snapshot builds
+resolve revision dates without writing captured freshness history. Changes made
+by checks to captured source or history still invalidate the result.
+Node checks receive the installed tool's dependency search paths through
+`NODE_PATH` for CommonJS resolution; ESM does not use it. Consumer dependencies
+are not copied. Missing executables or Node modules are `unavailable`.
+Model/evaluator hooks are skipped. Executable metadata/highlighting
+extensions currently return `unavailable` without invocation. No provider is chosen
+and no semantic review, automatic rewrite, application or publication occurs.
+
+`--artifacts DIRECTORY` chooses a new, exclusive artifact directory; otherwise a
+temporary directory is retained. Baselines and artifacts must be outside the
+project or inside its excluded `.shoalrun` directory. Canonical path checks prevent
+source/output collisions, including filesystem aliases. Results report the snapshot
+ID, report/site/captured-project locations and cleanup instructions. Remove only
+the reported artifact directory when finished. Validation starts no service. Use the separate snapshot review/preview commands
+below to inspect this captured result.
+
+Validation JSON schema version 1 has `kind: shoalrun-authoring-validation`, `status`,
+`snapshotId`, project/config identity, declared `baseline`, `changed` operations
+and before/current digests, full `inputs`/`excluded` lists, `dependencies`, content,
+config and validator digests, `runtimeDependencies`, `checks`, `findings`,
+`coverage`, `artifacts` and `freshness`. Coverage distinguishes current authored
+paths, affected paths, actual rendered routes/Markdown twins and affected paths
+that did not render. Findings include stable codes, severity, owning file, exact
+line/column/key when established, related collision files, explanation, canonical
+reference and next action. Compiler failure can stop later checks; unrendered
+affected pages remain visible. A build does not establish factual correctness.
+
+Validation status is `ok`, `failed`, `incomplete` (skipped configured checks),
+`unavailable` or `stale`. Only `ok` exits 0. Request/capture failures exit 1 with
+`{ schemaVersion: 1, status: "error", error: { code, message } }`; capture codes
+include `invalid_input`, `unsafe_path`, `stale_input`, `capture_limit` and
+`unsupported_dependency`. `validation-status` exits 0 only for a still-current
+`ok` report; it returns individual source/baseline/validator/artifact change flags
+and the next validation action. It performs no build or source writes.
+
+Capture verifies file identity/size/time/mode around reads and compares complete
+inventories after copying and after validation. Persistent concurrent edits cause
+a stale result rather than apparently successful mixed inputs. Report and artifact
+digests bind the checked content and core validator code/assets/configuration.
+Freshness includes new/deleted source files, baseline changes and relevant renderer
+configuration. This detects changes between checks, not an OS transaction or proof
+against a file changing and reverting between observations. Installed transitive
+runtime code is identified by package configuration; complete clean-install/version
+compatibility remains a later gate. Recheck applicability after subsequent edits.
+
+The public `@shoalrun/cli/authoring` entry adds `captureAuthoringBaseline(configFile)`,
+`writeAuthoringBaseline(configFile, output)`,
+`validateAuthoringChanges(configFile, { files?, ids?, baselineFile?, artifactsDirectory?, runConfiguredChecks? })`,
+`authoringValidationStatus(reportFile)`, `snapshotSchemaVersion` and matching types.
+API version 1 and the existing checked plan/apply contracts remain compatible.
+
+## Snapshot review and preview
+
+```sh
+shoalrun docs review /path/from/validation/report.json
+shoalrun docs review /path/from/validation/report.json --format markdown
+shoalrun docs preview /path/from/validation/report.json --port 8771
+```
+
+Review returns `kind: shoalrun-authoring-review`, schema version 1, the snapshot ID,
+validation status and current freshness. It identifies the baseline and changed-file
+operations/digests. Results include checks, findings and source/reference locations,
+coverage, affected HTML/Markdown routes and artifact paths, dependencies and next action. Baselines contain digests rather than earlier source contents;
+`diff.available` is false with the declared basis and an explanation. Harness-owned
+evidence and optional reviewer/disposition slots are explicitly unpopulated.
+Configuration/dependency/deletion changes include every rendered page, including
+generated API references; authored-only changes list affected pages. Page origin and
+selection scope are explicit. No semantic review is implied by compiler success. Review exits 0 only for current
+`ok`; errors use the validation JSON envelope even in Markdown mode.
+
+Preview binds only to `127.0.0.1`, defaults to port 8771, and accepts port 0 for an
+allocated port. It emits JSON with `kind: shoalrun-authoring-preview`, snapshot ID,
+origin, review/status URLs, all affected rendered page URLs, private serving-copy
+path, validation review and lifecycle. It remains a foreground process. Open the
+returned URL with your harness's normal browser interaction. Ctrl-C/SIGTERM closes
+connections, removes only the private copy and emits a stopped record. Retained
+validation artifacts remain separate; a forced kill can leave the serving copy.
+
+The private copy is checked against the validation site digest. Changed/missing
+artifacts refuse startup or serving. A stale working tree can be inspected as a
+historical snapshot with a visible banner. HTML pages poll freshness every two
+seconds; Markdown remains the captured output with an `X-Shoalrun-Snapshot` HTTP
+header. Failed/skipped checks retain their actual status while previewing. No
+watching/rebuilding occurs: edit, validate again, stop and restart with the new
+report. The copy limit is 20,000 regular files and 512 MiB; symlinks are rejected.
+The preview is a local development service for trusted project artifacts.
+
+The public library adds `authoringReview(reportFile)`,
+`authoringReviewMarkdown(review)`, and
+`startAuthoringPreview(reportFile, { port? })`. The controller exposes `server`,
+`review()` and idempotent `close()` plus the connection metadata. Always await
+`close()` in cleanup. API version 1 remains unchanged; capabilities add
+`snapshot-preview` and `authoring-review-report`.

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## 0.1.0-alpha.12 — 2026-10-27
+
+- Refresh the bundled documentation from the reviewed public site: organize navigation into Docs, Reference, Examples, and Project; use installed-package commands in customer workflows; and standardize component reference sections.
+- Explain HTML, Markdown, and agent behavior across feature references, and remove customer-facing embedding instructions for the site’s theme demo.
+
+Upgrade to alpha.12 to use the refreshed offline documentation through the CLI and MCP tools. Runtime behavior, components, and configuration are unchanged from alpha.11.
+
+## 0.1.0-alpha.11 — 2026-10-27
+
+- Move package distribution to the public npm registry. New installations need no GitHub package access or token. Existing users should remove the old `@shoalrun` registry override and update their manifest and lockfile together; see the README.
+- Lead the quickstart with the showcase and explain how to replace the fictional API without leaving broken Cedar operation bindings.
+- Add package homepage, repository, and issue links, and document the maintainer-led contribution policy and alpha expectations.
+
+This release changes distribution and onboarding. Existing site configuration and output contracts remain compatible with alpha.10.
+
+## 0.1.0-alpha.10 — 2026-10-27
+
+- Let mobile header tools share a row when space permits; anchor search results within the available header width.
+- Raise small reader, code, and API control labels and navigation metadata; keep ordinary list prose within the same reading measure as paragraphs.
+- Include page type and full-page token count in compact discovery and navigation indexes while preserving the 2,000-token index budget.
+- Add `shoalrun init --starter showcase`: an editable Cedar Parcel handbook with component examples, diagrams, reader views, a landing page, local-workflow cookbook, and generated API references.
+
+## 0.1.0-alpha.9 — 2026-10-27
+
+- Documentation pages put the article before the full navigation in HTML, so
+  readers and agents reach the page content sooner. Desktop sidebars stay on the
+  left. On smaller screens, the article is followed by the outline/API examples
+  and documentation navigation.
+- Desktop keyboard skip links appear on focus without adding a navigation row.
+  On narrow screens, one Menu button opens section links and page navigation in
+  a drawer; closing it restores focus and the article's scroll position.
+- The mobile page outline sits below the introduction in an On this page
+  disclosure. Navigation remains available through ordinary links and native
+  disclosures without JavaScript.
+
+## 0.1.0-alpha.7 and 0.1.0-alpha.8 — 2026-10-26
+
+These releases keep exported images and links with the correct document and let
+AI assistants find documentation through smaller topic directories. Upgrade to
+alpha.8 and rebuild to receive both sets of changes.
+
+### Topic discovery (alpha.8)
+
+- Compact discovery now splits growing catalogs into topic indexes with a
+  2,000-token limit per index. Topics use publication and primary taxonomy area,
+  falling back to page type. Large topics and navigation indexes split again
+  automatically; all published pages and standalone-section links remain reachable.
+- `llms.txt` remains the complete catalog. Consumers of `llms.min.txt` must follow
+  topic-index links when present instead of expecting every page in the first read.
+
+### Export and package hardening (alpha.7)
+
+The export manifest remains at schema version 1.
+
+- Pages sharing a website route retain their own local images and document links
+  in exported HTML and Markdown. This includes cards, related reading, cookbook
+  choices, deprecation notices, and changelog notices.
+- The manifest schema rejects traversal segments, empty path segments, and unsafe
+  export mount paths.
+- Output commits reject unsafe artifact paths and duplicate route aliases before
+  writing. Symlinked output destinations are refused, and aliases of a parent
+  directory share the same output lock.
+- The help-drawer example moves keyboard focus into opened content, follows scoped
+  anchors, and restores focus to its launcher when closed with Escape.
+- MCP server and client dependencies move to 2.3.0, Zod to 4.6.6, and KaTeX to
+  0.18.2. MCP tool arguments are limited to 1,024 elements before schema validation;
+  HTTP requests retain the 64 KiB body limit and per-request server instances.
+- Development dependencies receive compatible advisory fixes. Full test runs cap
+  concurrency at four files, rebuild tests use complete server events, and skill
+  validation checks Python prerequisites once with setup instructions.
+- Package smoke checks enforce an explicit inventory and can exercise the
+  installed help-drawer example in a browser with `--clean-install --browser`.
+
+### Compatibility
+
+Choose a real output directory rather than a symlink as the build or export
+destination. Parent-directory symlinks remain supported. This is still an alpha;
+the existing configuration and output compatibility policy applies.
+
+### Security references
+
+The dependency updates address the advisories for
+[MCP connection isolation](https://github.com/advisories/GHSA-jm63-cq47-j5jp),
+[MCP input validation](https://github.com/advisories/GHSA-46jr-4wx8-v453),
+[MCP bearer-token audience checks](https://github.com/advisories/GHSA-rvq5-wwqv-78pq),
+[Zod collection validation](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5), and
+[KaTeX inherited settings](https://github.com/advisories/GHSA-238p-pmpm-9mq7).

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.