diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..e9397ad1e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,90 @@ +name: Bug report +description: Report a reproducible problem or unexpected behavior in Huabu +title: '[Bug]: ' +body: + - type: markdown + attributes: + value: | + Thanks for helping improve Huabu. Please search existing issues before submitting a new report. + + Do not include API keys, access tokens, private documents, personal information, or other sensitive data. + + - type: checkboxes + id: existing-issues + attributes: + label: Existing issues + options: + - label: I searched the existing issues and did not find a report of the same problem. + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the behavior you observed, including any error message. + placeholder: Tell us what went wrong. + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: What did you expect? + description: Describe what you were trying to do and what you expected Huabu to do instead. + placeholder: Tell us what should have happened. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: List the shortest sequence of steps that triggers the problem. + placeholder: | + 1. Open Huabu and ... + 2. Select ... + 3. Observe ... + validations: + required: true + + - type: dropdown + id: frequency + attributes: + label: How often does it happen? + options: + - Every time + - Sometimes + - Only once + - Not sure + validations: + required: true + + - type: textarea + id: system-information + attributes: + label: System information + description: In the desktop app, choose Help → Troubleshooting → Copy System Information, then paste the result here. + render: shell + validations: + required: true + + - type: textarea + id: ai-details + attributes: + label: AI-related details + description: Complete this only if the problem involves an AI response or edit. + placeholder: Include the interaction mode, agent, provider and model, selected context, relevant output, and whether proposed changes were applied. Never include an API key. + + - type: textarea + id: screenshots-and-logs + attributes: + label: Screenshots and logs + description: Drag screenshots, recordings, or the relevant part of server.log here after removing sensitive information. + + - type: checkboxes + id: sensitive-information + attributes: + label: Sensitive information + options: + - label: I reviewed this report and its attachments and removed sensitive information. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..fabf850db --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Huabu Handbook + url: https://microsoft.github.io/Huabu/docs/ + about: Read the user handbook before reporting a usage question. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 000000000..f7a1799d4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,43 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + quality: + name: Lint / Format / Typecheck / Test / Build / Headers + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up pnpm + uses: pnpm/action-setup@v4 + with: + version: 10.34.3 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + cache-dependency-path: pnpm-lock.yaml + + - name: Install dependencies + run: pnpm install --frozen-lockfile --ignore-scripts + + - name: Run quality checks + run: pnpm check + env: + DOCS_BASE_PATH: /Huabu/ + DOCS_CANONICAL_ORIGIN: https://microsoft.github.io diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000..1bb2ab772 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,66 @@ +name: Deploy user handbook + +on: + workflow_dispatch: + push: + branches: + - main + paths: + - 'apps/docs/**' + - '.github/workflows/deploy-docs.yml' + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Check out Huabu + uses: actions/checkout@v4 + + - name: Set up pnpm + uses: pnpm/action-setup@v4 + with: + version: 10.34.3 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + cache-dependency-path: pnpm-lock.yaml + + - name: Install dependencies + run: pnpm install --frozen-lockfile --ignore-scripts + + - name: Build handbook + run: pnpm --filter @huabu/docs build + env: + DOCS_BASE_PATH: /Huabu/ + DOCS_CANONICAL_ORIGIN: https://microsoft.github.io + + - name: Configure GitHub Pages + uses: actions/configure-pages@v5 + + - name: Upload handbook artifact + uses: actions/upload-pages-artifact@v3 + with: + path: apps/docs/dist + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/sync-release.yml b/.github/workflows/sync-release.yml new file mode 100644 index 000000000..f754fb0b4 --- /dev/null +++ b/.github/workflows/sync-release.yml @@ -0,0 +1,148 @@ +name: Sync upstream release + +on: + workflow_dispatch: + inputs: + destination_tag: + description: 'Destination tag; leave empty to use source tag' + required: false + type: string + +permissions: + contents: write + +concurrency: + group: sync-release-${{ inputs.destination_tag }} + cancel-in-progress: false + +jobs: + sync-release: + runs-on: ubuntu-latest + + steps: + - name: Read latest source release + shell: bash + env: + SOURCE_REPO: ${{ secrets.SOURCE_REPOSITORY }} + SOURCE_TOKEN: ${{ secrets.SOURCE_REPO_TOKEN }} + REQUESTED_DEST_TAG: ${{ inputs.destination_tag }} + run: | + set -euo pipefail + + GH_TOKEN="$SOURCE_TOKEN" gh release view \ + --repo "$SOURCE_REPO" \ + --json tagName,body,isPrerelease \ + > source-release.json + + SOURCE_TAG="$(jq -r '.tagName' source-release.json)" + IS_PRERELEASE="$(jq -r '.isPrerelease' source-release.json)" + + DEST_TAG="$REQUESTED_DEST_TAG" + if [[ -z "$DEST_TAG" ]]; then + DEST_TAG="$SOURCE_TAG" + fi + + for tag in "$SOURCE_TAG" "$DEST_TAG"; do + if [[ "$tag" == -* ]] || ! git check-ref-format "refs/tags/$tag"; then + echo "Invalid release tag: $tag" >&2 + exit 1 + fi + done + + jq -r '.body // ""' source-release.json > release-notes.md + + { + echo "source_tag=$SOURCE_TAG" + echo "dest_tag=$DEST_TAG" + echo "is_prerelease=$IS_PRERELEASE" + } >> "$GITHUB_OUTPUT" + id: release + + - name: Download source assets + id: download + shell: bash + env: + SOURCE_REPO: ${{ secrets.SOURCE_REPOSITORY }} + SOURCE_TOKEN: ${{ secrets.SOURCE_REPO_TOKEN }} + SOURCE_TAG: ${{ steps.release.outputs.source_tag }} + run: | + set -euo pipefail + + mkdir -p assets + + if ! GH_TOKEN="$SOURCE_TOKEN" gh release download \ + "$SOURCE_TAG" \ + --repo "$SOURCE_REPO" \ + --dir assets; then + echo "No downloadable assets for $SOURCE_TAG." + fi + + asset_count="$(find assets -maxdepth 1 -type f | wc -l)" + if (( asset_count == 0 )); then + echo "Source release has no assets; skipping publish." + echo "has_assets=false" >> "$GITHUB_OUTPUT" + else + echo "has_assets=true" >> "$GITHUB_OUTPUT" + fi + + - name: Create or update destination release + if: steps.download.outputs.has_assets == 'true' + shell: bash + env: + DEST_REPO: ${{ github.repository }} + DEST_TOKEN: ${{ github.token }} + SOURCE_TAG: ${{ steps.release.outputs.source_tag }} + DEST_TAG: ${{ steps.release.outputs.dest_tag }} + IS_PRERELEASE: ${{ steps.release.outputs.is_prerelease }} + run: | + set -euo pipefail + + TITLE="Huabu $SOURCE_TAG" + + prerelease_args=() + if [[ "$IS_PRERELEASE" == "true" ]]; then + prerelease_args+=(--prerelease) + fi + + if GH_TOKEN="$DEST_TOKEN" gh release view \ + "$DEST_TAG" \ + --repo "$DEST_REPO" >/dev/null 2>&1; then + + echo "Updating existing release $DEST_TAG" + + GH_TOKEN="$DEST_TOKEN" gh release edit \ + "$DEST_TAG" \ + --repo "$DEST_REPO" \ + --title "$TITLE" \ + --notes-file release-notes.md \ + --prerelease="$IS_PRERELEASE" + else + echo "Creating release $DEST_TAG" + + GH_TOKEN="$DEST_TOKEN" gh release create \ + "$DEST_TAG" \ + --repo "$DEST_REPO" \ + --title "$TITLE" \ + --notes-file release-notes.md \ + "${prerelease_args[@]}" + fi + + - name: Upload destination assets + if: steps.download.outputs.has_assets == 'true' + shell: bash + env: + DEST_REPO: ${{ github.repository }} + DEST_TOKEN: ${{ github.token }} + DEST_TAG: ${{ steps.release.outputs.dest_tag }} + run: | + set -euo pipefail + + mapfile -d '' assets < <( + find assets -maxdepth 1 -type f -print0 + ) + + GH_TOKEN="$DEST_TOKEN" gh release upload \ + "$DEST_TAG" \ + "${assets[@]}" \ + --repo "$DEST_REPO" \ + --clobber diff --git a/.gitignore b/.gitignore index d5a18deed..aa0b14d44 100644 --- a/.gitignore +++ b/.gitignore @@ -315,6 +315,11 @@ FakesAssemblies/ .ntvs_analysis.dat node_modules/ +# Huabu handbook build output +apps/docs/.ssr/ +apps/docs/dist/ +apps/docs/tsconfig.node.tsbuildinfo + # Visual Studio 6 build log *.plg diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 000000000..4c6ba3818 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,4 @@ +**/dist/ +**/node_modules/ +**/.ssr/ +**/*.tsbuildinfo diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 000000000..8beea539b --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,9 @@ +{ + "singleQuote": true, + "trailingComma": "all", + "tabWidth": 2, + "useTabs": false, + "endOfLine": "lf", + "arrowParens": "always", + "plugins": ["prettier-plugin-tailwindcss"] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..02e6376c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +# Contributing to Huabu + +Thank you for your interest in Huabu. + +## Current contribution scope + +The current contribution scope focuses on bug reports, documentation feedback, and research feedback submitted through the [Huabu issue tracker](https://github.com/microsoft/Huabu/issues). + +Before opening an issue, search existing issues, use the latest available release, and follow the guidance in [SUPPORT.md](SUPPORT.md). Do not include API keys, access tokens, private documents, personal information, or other sensitive data in public issues, logs, or screenshots. + +Security vulnerabilities must not be reported through public GitHub issues. Follow [SECURITY.md](SECURITY.md) to report them privately. + +## Contributor License Agreement + +Most contributions require agreement to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use the contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com). When a pull request is submitted, a CLA bot will determine whether the agreement is required and provide instructions. + +## Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), review the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/), or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with additional questions or comments. + +## License + +By contributing to this repository, you agree that your contributions will be licensed under the [MIT License](LICENSE), unless explicitly stated otherwise. diff --git a/RAI_README.md b/RAI_README.md new file mode 100644 index 000000000..7338a4949 --- /dev/null +++ b/RAI_README.md @@ -0,0 +1,105 @@ +# Microsoft Responsible AI Transparency Documentation for Research - Huabu + +## Overview + +Huabu is a canvas-based interaction framework for human–AI collaboration. It provides a shared two-dimensional workspace where humans and AI agents co-work on the same materials — documents, web pages, notes, and AI conversations — arranged as persistent, spatially organized nodes. + +Huabu is designed around three principles: externalizing thinking, so that the intermediate structure of work becomes visible and manipulable; sharing a cognitive space with AI, so that agents can follow broader intent rather than only the latest instruction; and supporting natural interaction — handwriting, touch, and speech alongside typing — so that users can stay in flow while ideas are still forming. + +### WHAT CAN Huabu do + +Huabu was developed to support the early, exploratory stages of complex work — where the central challenge is deciding what to do, rather than executing well-formed instruction. On the canvas, users can externalize ideas, notes, references, and AI outputs as persistent nodes; arrange them spatially to reflect relationships, priorities, and uncertainty; and let AI agents observe the evolving workspace to help organize materials, synthesize across nodes, identify what remains unresolved, and hand off mature ideas to downstream execution agents. + + + +### INTENDED USES + +Huabu is best suited for open-ended, exploratory knowledge work — including research, planning, ideation, and early-stage design — where intent is still forming and benefits from being externalized and discussed in a shared visual space rather than a linear chat thread. + +Huabu is being shared with the research community to facilitate reproduction of our results and foster further research in this area. + +Huabu is intended to be used by domain experts who are independently capable of evaluating the quality of outputs before acting on them. + +### OUT-OF-SCOPE USES + +Huabu is not well suited for tasks that require a single authoritative answer, time-critical decision making, or workflows where the AI’s outputs would be acted on without human review. It is also not suited for users who lack the domain expertise needed to evaluate AI-generated content on the canvas, since responsibility for assessing quality and correctness rests with the user. + +We do not recommend using Huabu in commercial or real-world applications without further testing and development. It is being released for research purposes. + +Huabu was not designed or evaluated for all possible downstream purposes. Developers should consider its inherent limitations as they select use cases, and evaluate and mitigate for accuracy, safety, and fairness concerns specific to each intended downstream use. + +Without further testing and development, Huabu should not be used in sensitive domains where inaccurate outputs could suggest actions that lead to injury or negatively impact an individual's legal, financial, or life opportunities. + +We do not recommend using Huabu in the context of high-risk decision making (e.g. in law enforcement, legal, finance, or healthcare). + +## HOW TO GET STARTED + +To begin using Huabu, download the latest installer for your operating system from the [GitHub Releases page](https://github.com/microsoft/Huabu/releases), then run the installer and launch the application. See the repository README for instructions on connecting a base LLM/MLLM and configuring example workflows. + +## Evaluation + +Huabu was evaluated on its ability to support exploratory knowledge work scenarios — including research synthesis, planning, and ideation — through internal dogfooding and qualitative studies with researchers. + + + +### EVALUATION METHODS + +We used qualitative observation, task walk-throughs, and structured user feedback from internal dogfooding sessions to measure Huabu’s performance. + +We compared the performance of Huabu against the linear chat baseline that is the dominant paradigm today using participant-reported feedback across research, planning, and ideation scenarios. + +The model used for evaluation was GPT 5.5. For more on this specific model, please see [Introducing GPT-5.5 | OpenAI](https://openai.com/index/introducing-gpt-5-5/). + +Results may vary if Huabu is used with a different model based on its unique design, configuration and training. + +### EVALUATION RESULTS + +At a high level, we found that Huabu performed well in helping users externalize and organize early-stage thinking, reduced the cognitive load of holding intermediate ideas in working memory, and made it easier for AI agents to act on the broader context of a task rather than only the latest message. + +## LIMITATIONS + +Huabu was developed for research and experimental purposes. Further testing and validation are needed before considering its application in commercial or real-world scenarios. It does not control any downstream agents, and users are responsible for configuring them safely. + +Huabu was designed and tested using the English language. Performance in other languages may vary and should be assessed by someone who is both an expert in the expected outputs and a native speaker of that language. + +Outputs generated by AI may include factual errors, fabrication, or speculation. Users are responsible for assessing the accuracy of generated content. All decisions leveraging outputs of the system should be made with human oversight and not be based solely on system outputs. + +Huabu inherits any biases, errors, or omissions produced by the model you choose to use with it. Developers are advised to choose an appropriate MLLM carefully, depending on the intended use case. + +There has not been a systematic effort to ensure that systems using Huabu are protected from security vulnerabilities such as indirect prompt injection attacks. Any systems using it should take proactive measures to harden their systems as appropriate. + +## BEST PRACTICES + +Better performance can be achieved by curating canvas content carefully, keeping nodes concise and well-labeled, and grouping related materials spatially so that the AI agent can interpret structure from the layout. Reviewing AI suggestions before acting on them — particularly before handing canvas content off to downstream execution agents — is strongly recommended. + +We strongly encourage users to use LLMs/MLLMs that support robust Responsible AI mitigations, such as Azure Open AI (AOAI) services. Such services continually update their safety and RAI mitigations with the latest industry standards for responsible use. For more on AOAI’s best practices when employing foundations models for scripts and applications: + +- [What is Azure AI Content Safety?](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview) +- [Overview of Responsible AI practices for Azure OpenAI models](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/overview) +- [Azure OpenAI Transparency Note](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/transparency-note) +- [OpenAI’s Usage policies](https://openai.com/policies/usage-policies) +- [Azure OpenAI’s Code of Conduct](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/code-of-conduct) + +Users are responsible for sourcing their datasets legally and ethically. This could include securing appropriate rights, ensuring consent for use of audio/images, and/or the anonymization of data prior to use in research. + +Users are reminded to be mindful of data privacy concerns and are encouraged to review the privacy policies associated with any models and data storage solutions interfacing with Huabu. + +It is the user’s responsibility to ensure that the use of Huabu complies with relevant data protection regulations and organizational guidelines. + +Developers should follow transparency best practices and inform end-users they are interacting with an AI system. + +## LICENSE + +MIT License + +Nothing disclosed here, including the Out of Scope Uses section, should be interpreted as or deemed a restriction or modification to the license the code is released under. + +## TRADEMARKS + +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies. + +## CONTACT + +This research was conducted by members of [Microsoft Research](https://www.microsoft.com/en-us/research/). We welcome feedback and collaboration from our audience. If you have suggestions, questions, or observe unexpected/offensive behavior in our technology, please contact us at nanchen@microsoft.com. + +If the team receives reports of undesired behavior or identifies issues independently, we will update this repository with appropriate mitigations. diff --git a/README.md b/README.md index ffd0cdd5c..dc6e0535e 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,68 @@ -# Project +
Where you and your agents think together.
-As the maintainer of this project, please make a few updates: ++ User Handbook · + Download · + Feedback +
-- Improving this README.MD file to provide a great experience -- Updating SUPPORT.MD with content about this project's support experience -- Understanding the security reporting process in SECURITY.MD -- Remove this section from the README +Huabu is a spatial workspace for thinking with AI. It keeps ideas and AI work persistent, visible, and connected, so collaboration can continue across sessions instead of disappearing into isolated chat threads. -## Contributing +## Core Features + +- **Bring scattered information together** — drag ideas, notes, documents, and outputs from different chat sessions and sources into one Space, so everything relevant stays visible and connected. +- **Organize your thinking with AI** — work with AI to arrange information, uncover relationships, and clarify ideas while reviewing and controlling every proposed change. +- **Let your agents work with richer context** — bring your own agents into a Space, where they can understand not only the materials you provide, but also how those materials relate to one another—helping them better grasp your intent and do more relevant work. + + > Source code will be released in a future update. + +## Download and Install + +This initial release distributes packaged desktop applications through [GitHub Releases](https://github.com/microsoft/Huabu/releases/latest). + +1. Download the latest package for your platform from the Releases page. +2. On macOS, open the `.dmg`; on Windows, run the `.exe` installer. +3. Launch Huabu and choose a local folder as your **Home**. + +The current desktop packages target macOS on Apple silicon and Windows on x64. Available packages may vary by release; consult the release notes before installing. + +## Quick Start + +Follow the [Huabu User Handbook](https://microsoft.github.io/Huabu/docs/) for setup instructions, model configuration, core concepts, and guidance on creating and working in your first Space. The handbook is the canonical source for product usage instructions. + +Huabu does not provide an LLM service as part of the application. Use of a model or external capability may require a separate account, credentials, subscription, or usage charges from its provider. -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com). +## Data, Credentials, and Connected Services -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. +Huabu stores Spaces and their materials in the Home folder selected by the user. Credentials saved in the packaged desktop application are encrypted at rest using operating-system-protected storage. + +Huabu does not send telemetry, crash reports, diagnostic logs, or usage data to Microsoft. + +When an AI feature is used, the configured model provider or connected service may receive the prompt and relevant Space content needed to fulfill the request. External agents may also read or modify files within the working directory configured for them. Review the terms, privacy practices, data-handling controls, and permissions of every provider or agent before connecting it, and do not provide sensitive material unless its use is authorized. + +## Research Status and Responsible Use + +Huabu is released for research and experimental use. AI-generated output may be inaccurate, incomplete, biased, or unsafe, and Huabu has not been evaluated for every language, model, or downstream scenario. Do not use it for high-risk or time-critical decisions, or in workflows where output is acted upon without qualified human review. + +For the complete intended-use statement, evaluation summary, limitations, and responsible-use guidance, read [RAI_README.md](RAI_README.md). + +## Support and Feedback + +Community support is available on a best-effort basis through the [Huabu issue tracker](https://github.com/microsoft/Huabu/issues). See [SUPPORT.md](SUPPORT.md) for support guidance. Report security vulnerabilities privately by following [SECURITY.md](SECURITY.md). + +## Contributing -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +We welcome bug reports, documentation feedback, and research feedback. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidance and Contributor License Agreement requirements. This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). ## Trademarks -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft -trademarks or logos is subject to and must follow -[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third parties' policies. +## License +The materials included directly in this repository are licensed under the [MIT License](LICENSE), except where otherwise noted. The packaged Huabu application distributed through GitHub Releases is provided under the license terms included with that release. diff --git a/SECURITY.md b/SECURITY.md index e751608fc..656f79188 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -11,4 +11,4 @@ For security reporting information, locations, contact information, and policies please review the latest guidance for Microsoft repositories at [https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md). - \ No newline at end of file + diff --git a/SUPPORT.md b/SUPPORT.md index eaf439aec..b93ce8636 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,25 +1,23 @@ -# TODO: The maintainer of this repo has not yet edited this file +# Support -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? +## How to get help -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps. -- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide. +Community support is available through the [Huabu GitHub issue tracker](https://github.com/microsoft/Huabu/issues) on a best-effort basis. -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* +Before opening an issue: -# Support +1. Update Huabu to the latest available version and confirm that the problem still occurs. +2. Search [existing issues](https://github.com/microsoft/Huabu/issues) to avoid duplicates. +3. Follow the [Report an Issue guide](https://microsoft.github.io/Huabu/docs/reference/issues) to collect reproduction steps, system information, and relevant screenshots or logs. + +If an existing issue describes the same problem, add any new details there instead of opening a duplicate. Otherwise, [create a new issue](https://github.com/microsoft/Huabu/issues/new/choose). -## How to file issues and get help +Never include API keys, access tokens, private documents, personal information, or other sensitive data in a public issue. Review and redact screenshots and logs before uploading them. -This project uses GitHub Issues to track bugs and feature requests. Please search the existing -issues before filing new issues to avoid duplicates. For new issues, file your bug or -feature request as a new Issue. +## Security issues -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. +Do not report security vulnerabilities through public GitHub issues. Follow the instructions in [SECURITY.md](SECURITY.md) instead. -## Microsoft Support Policy +## Microsoft Support Policy -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +Support for Huabu is limited to the community resources listed above. diff --git a/apps/docs/.npmrc b/apps/docs/.npmrc new file mode 100644 index 000000000..538f0f031 --- /dev/null +++ b/apps/docs/.npmrc @@ -0,0 +1 @@ +registry=https://registry.npmjs.org/ diff --git a/apps/docs/README.md b/apps/docs/README.md new file mode 100644 index 000000000..0b759be42 --- /dev/null +++ b/apps/docs/README.md @@ -0,0 +1,77 @@ +# Huabu User Handbook + +This package contains the source for the public Huabu User Handbook at [https://microsoft.github.io/Huabu/docs/](https://microsoft.github.io/Huabu/docs/). It is an independent Vite application maintained directly in the Huabu repository. + +## Requirements + +- Node.js 22 +- pnpm 10.34.3 + +## Install dependencies + +From the repository root, run: + +```sh +pnpm install +``` + +## Local development + +Start the Vite development server: + +```sh +pnpm dev +``` + +The development server defaults to `http://localhost:43127`. Set `DOCS_PORT` to use another port. Search is unavailable in development because Pagefind indexes are generated during the production build. + +To preview the complete generated site, including search: + +```sh +pnpm build +pnpm preview +``` + +The preview server defaults to `http://localhost:43128`. + +## Quality checks + +Run the complete repository quality gate from the repository root before opening a pull request: + +```sh +pnpm check +``` + +The root command runs these checks across every workspace package in order: + +- `pnpm lint` — applies the repository ESLint rules to all supported source files. +- `pnpm format:check` — verifies repository-wide Prettier formatting without modifying files. +- `pnpm typecheck` — runs each workspace package's type checker when present. +- `pnpm test` — runs each workspace package's test suite when present. +- `pnpm build` — builds each workspace package when present; for this package it also prerenders, indexes, and validates the deployable static artifact. +- `node scripts/check-headers.mjs` — verifies Microsoft MIT headers across tracked source files. + +To apply safe automatic lint and formatting fixes: + +```sh +pnpm lint:fix +pnpm format +``` + +Review automatic changes before committing them. + +## Tests + +Run all tests once: + +```sh +pnpm test +``` + +Run tests in watch mode while developing: + +```sh +pnpm test:watch +``` + +Tests use Vitest with Happy DOM. Add or update tests when changing routing, navigation, base-path behavior, or documentation data with executable invariants. diff --git a/apps/docs/index.html b/apps/docs/index.html new file mode 100644 index 000000000..97403eb91 --- /dev/null +++ b/apps/docs/index.html @@ -0,0 +1,19 @@ + + + + + + + + + +